astel 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19a38e5beaa849b77b5d60ea2d46b1913e589a1892dd36fc6797e34e5dbd2738
-  data.tar.gz: 7de828db0d6c9e6ea66179f2f931308b9609ccade0047dc99e0b5f77e61ead5f
+  metadata.gz: f3aa35253044b63edd2bcce05297d78c15740ac93627b8d32ec909eba8dd2ce1
+  data.tar.gz: 495161fcfbd3b410f7e220002f177afa8a5c9892f97ab6a3a7360b8005e414c6
 SHA512:
-  metadata.gz: 8364cddfb8fe41deb8770e0f3ca105467820030d77c3563184aa9d087cbd8de2649d05db67058b18f04476ef410f945ef948dc12f2226bd55d607fa4ba683dfb
-  data.tar.gz: 4feb4b4cd00035245cf4b992612f0d51c67e2d7fa74decaea77b59912a481e9cc6129938ded3882b3aecd33a186535783ecf00f755e7347b08ca820d14bbd550
+  metadata.gz: aee6be8604da7c4b6bfa7ff2d4c010ba987501d4c1238852095201144a1f8068807eeeaf52b59b32d6b3e2adcbe4a52703f97c2b09f082bab76ce979986c11df
+  data.tar.gz: 9365ceb989c157954fbb88fd473c6c73a6c8e8548ddd0642da65ae890a5af51ae9dcba9e8512433cb3dcac08ce19672325be307b4df319ff83de4dc44c7b8ce6

data/CHANGELOG.md

@@ -5,6 +5,17 @@ project follows Semantic Versioning.
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-08-30
+
+- Add atomic `Rewriter#transaction` and `#merge!` operations
+- Accept same-offset insertions by default, with an opt-in strict policy
+- Add rewrite syntax validation, wrapping, and encoding compatibility checks
+- Add source formatting and location APIs
+- Add opt-in refactoring helpers with `require "astel/refactor"`
+- Add dependency-free unified diffs with `require "astel/diff"`
+- Add weekly rewrite-and-reparse fuzzing against real gem sources
+- Keep wrapping and comment attachment atomic and idempotent across edge cases
+
 ## [0.1.0] - 2026-07-15
 
 - Initial release

data/README.md

@@ -1,5 +1,6 @@
 # Astel
 
+[![Gem Version](https://badge.fury.io/rb/astel.svg)](https://badge.fury.io/rb/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)
 
@@ -116,9 +117,67 @@ 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
+The rewriter supports `replace`, `remove`, `insert_before`, `insert_after`, and
+`wrap`. Overlapping edits raise `Astel::Rewriter::ConflictError`, and
 `Astel::Rewriter#edits` returns an immutable snapshot of registered edits.
+Same-offset insertions are concatenated in registration order. Pass
+`duplicate_insertions: :raise` to retain the strict behavior from Astel 0.1.
+
+Group related edits atomically with a transaction:
+
+```ruby
+rewriter.transaction do |rw|
+  rw.replace(first.location, "first")
+  rw.replace(second.location, "second")
+end
+```
+
+The transaction returns `false` without registering any edits when a conflict
+occurs. Pass `raise_on_conflict: true` to raise instead. Use
+`rewrite(validate: :parse)` to reject rewritten source containing syntax errors.
+
+### Source formatting
+
+`SourceFile` exposes byte-based line and column lookup, line locations, source
+slicing, dominant newline detection, and indentation detection:
+
+```ruby
+source.line_at(node.location.start_offset)
+source.column_at(node.location.start_offset)
+source.indentation_at(node.location.start_offset)
+source.newline
+source.indent_unit
+```
+
+### Refactoring helpers
+
+Load semantic source-editing helpers explicitly:
+
+```ruby
+require "astel/refactor"
+
+rewriter = Astel::Rewriter.new(source)
+rewriter.remove_keyword_argument(call_node, :required)
+rewriter.insert_into_body(class_node, "def added\nend", position: :before_private)
+```
+
+See [Refactoring recipes](docs/refactor.md) for the complete API and examples.
+
+### Unified diffs
+
+Diff support is also opt-in and has no additional runtime dependency:
+
+```ruby
+require "astel/diff"
+
+puts rewriter.to_diff(context: 3)
+```
+
+As with Git-generated zero-context patches, `context: 0` requires
+`git apply --unidiff-zero`.
+
+See the [codemod guide](docs/codemod-guide.md) for an end-to-end example using
+the dispatcher, node patterns, transactions, validation, and diffs.
 
 ## Performance and concurrency
 
@@ -139,6 +198,13 @@ bundle exec ruby benchmark/node_pattern_bench.rb
 bundle exec ruby benchmark/rewriter_bench.rb
 ```
 
+## Scope
+
+Astel intentionally does not provide a nested action tree, file discovery,
+parallel execution, a CLI, a rule framework, or a parser compatibility layer.
+Those concerns stay in applications built on Astel. Source edits remain flat;
+overlapping ranges raise instead of being silently reordered or discarded.
+
 ## Development
 
 After checking out the repository, install dependencies and run the test suite:
@@ -154,6 +220,15 @@ Verify the packaged gem with:
 bundle exec ruby script/package_smoke.rb
 ```
 
+Run the deterministic source-rewrite fuzz check against Ruby source trees with:
+
+```sh
+SEED=123 bundle exec ruby script/fuzz.rb path/to/gem/sources
+```
+
+CI runs the same check weekly against Rails, RuboCop, Sidekiq, Faraday, and
+Prism source releases.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on

data/docs/codemod-guide.md

@@ -0,0 +1,51 @@
+# Codemod guide
+
+A codemod can parse, traverse, match, edit, validate, and display a diff using
+Astel and Prism alone.
+
+```ruby
+require "astel"
+require "astel/refactor"
+require "astel/diff"
+
+source = Astel::SourceFile.parse(path: "app/types/user_type.rb")
+raise "parse failed" unless source.valid?
+
+rewriter = Astel::Rewriter.new(source)
+pattern = Astel::NodePattern.compile(
+  "(call_node receiver: nil name: :field)"
+)
+
+dispatcher = Astel::Dispatcher.new
+dispatcher.on(:call_node) do |node|
+  next unless pattern.match?(node)
+  next unless rewriter.find_keyword_argument(node, :required)
+
+  rewriter.transaction do |rw|
+    rw.remove_keyword_argument(node, :required)
+    rw.insert_keyword_argument(node, "null: false")
+  end
+end
+dispatcher.run(source.ast)
+
+puts rewriter.to_diff
+File.write(source.path, rewriter.rewrite(validate: :parse)) unless rewriter.edits.empty?
+```
+
+Transactions keep rule-level changes atomic. If one staged edit conflicts, none
+of that transaction's edits are registered. Overlapping ranges remain errors;
+Astel does not build or reconcile a nested action tree.
+
+## TreeRewriter compatibility
+
+For non-overlapping ASCII edits, Astel's output is regression-tested against
+`Parser::Source::TreeRewriter` with 5,000 randomized operation sequences.
+
+There are two intentional semantic differences:
+
+- Astel uses byte offsets, while parser uses character offsets.
+- Same-offset insertions are emitted in registration order. TreeRewriter's
+  `insert_before` emits repeated insertions in reverse registration order.
+
+Use `duplicate_insertions: :raise` when duplicate insertions should be treated
+as conflicts.

data/docs/refactor.md

@@ -0,0 +1,87 @@
+# Refactoring recipes
+
+Load the helpers explicitly. Requiring `astel/refactor` adds them to every
+`Astel::Rewriter` instance.
+
+```ruby
+require "astel"
+require "astel/refactor"
+
+source = Astel::SourceFile.parse(path: "example.rb")
+rewriter = Astel::Rewriter.new(source)
+```
+
+## Keyword arguments and lists
+
+Find, remove, replace, or insert keyword arguments:
+
+```ruby
+argument = rewriter.find_keyword_argument(call_node, :required)
+rewriter.remove_keyword_argument(call_node, :required)
+rewriter.replace_keyword_key(argument, :method)
+rewriter.replace_keyword_value(argument, "false")
+rewriter.insert_keyword_argument(call_node, "null: false")
+```
+
+The list APIs accept `Prism::ArgumentsNode`, `Prism::ArrayNode`,
+`Prism::KeywordHashNode`, and `Prism::HashNode`:
+
+```ruby
+rewriter.remove_list_element(arguments, arguments.arguments.first)
+rewriter.remove_list_elements(arguments, arguments.arguments.values_at(0, 2))
+rewriter.insert_list_element(arguments, 1, "new_value")
+```
+
+Multiple removals are calculated together and registered as one edit, keeping
+comma handling atomic.
+
+## Add a method
+
+`insert_into_body` supports classes, modules, methods, singleton classes, and
+blocks. It detects the file's indentation and newline style.
+
+```ruby
+rewriter.insert_into_body(class_node, <<~RUBY, position: :before_private)
+  def active?
+    true
+  end
+RUBY
+```
+
+Positions are `:beginning`, `:end`, `:before_private`, `{ before: node }`, and
+`{ after: node }`.
+
+## Rewrite a constant path
+
+Use the core `replace` API when the AST location already identifies the exact
+source range:
+
+```ruby
+pattern = Astel::NodePattern.compile(
+  "(constant_path_node name: :OldClient)"
+)
+
+dispatcher = Astel::Dispatcher.new
+dispatcher.on(:constant_path_node) do |node|
+  rewriter.replace(node.location, "Services::NewClient") if pattern.match?(node)
+end
+dispatcher.run(source.ast)
+```
+
+## Formatting, lines, and comments
+
+```ruby
+rewriter.indentation_of(node)
+rewriter.indent(text, level: 1)
+rewriter.dedent(text)
+rewriter.reindent(text, to: node)
+
+rewriter.remove_line(node)
+rewriter.insert_line_before(node, "before")
+rewriter.insert_line_after(node, "after")
+rewriter.comment_out(node)
+
+rewriter.leading_comments(node)
+rewriter.trailing_comment(node)
+rewriter.remove_with_comments(node)
+```

data/lib/astel/diff.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative '../astel'
+
+module Astel
+  module Diff
+    module_function
+
+    def unified(before, after, path:, context: 3)
+      validate_options(path, context)
+      return '' if before == after
+
+      operations = operations(before.lines(chomp: false), after.lines(chomp: false))
+      annotated = annotate(operations)
+      hunks = hunk_ranges(annotated, context)
+      output = +"--- a/#{path}\n+++ b/#{path}\n"
+      hunks.each { |range| append_hunk(output, annotated[range]) }
+      output
+    end
+
+    def operations(before, after)
+      prefix = 0
+      prefix += 1 while prefix < before.length && prefix < after.length && before[prefix] == after[prefix]
+      suffix = 0
+      while suffix < before.length - prefix && suffix < after.length - prefix &&
+            before[-suffix - 1] == after[-suffix - 1]
+        suffix += 1
+      end
+
+      old_middle = before[prefix...(before.length - suffix)]
+      new_middle = after[prefix...(after.length - suffix)]
+      before.first(prefix).map { |line| [:equal, line] } +
+        lcs_operations(old_middle, new_middle) +
+        (suffix.zero? ? [] : before.last(suffix).map { |line| [:equal, line] })
+    end
+    private_class_method :operations
+
+    def lcs_operations(before, after)
+      # ponytail: LCS is O(n*m) on the changed middle; switch to Myers if large rewrites become common.
+      lengths = Array.new(before.length + 1) { Array.new(after.length + 1, 0) }
+      (before.length - 1).downto(0) do |old_index|
+        (after.length - 1).downto(0) do |new_index|
+          lengths[old_index][new_index] = if before[old_index] == after[new_index]
+                                            lengths[old_index + 1][new_index + 1] + 1
+                                          else
+                                            [lengths[old_index + 1][new_index],
+                                             lengths[old_index][new_index + 1]].max
+                                          end
+        end
+      end
+
+      result = []
+      old_index = 0
+      new_index = 0
+      while old_index < before.length || new_index < after.length
+        if old_index < before.length && new_index < after.length && before[old_index] == after[new_index]
+          result << [:equal, before[old_index]]
+          old_index += 1
+          new_index += 1
+        elsif new_index == after.length ||
+              (old_index < before.length && lengths[old_index + 1][new_index] >= lengths[old_index][new_index + 1])
+          result << [:delete, before[old_index]]
+          old_index += 1
+        else
+          result << [:insert, after[new_index]]
+          new_index += 1
+        end
+      end
+      result
+    end
+    private_class_method :lcs_operations
+
+    def annotate(operations)
+      old_line = 1
+      new_line = 1
+      operations.map do |type, line|
+        entry = { type: type, line: line, old_line: old_line, new_line: new_line }
+        old_line += 1 unless type == :insert
+        new_line += 1 unless type == :delete
+        entry
+      end
+    end
+    private_class_method :annotate
+
+    def hunk_ranges(operations, context)
+      changed = operations.each_index.reject { |index| operations[index][:type] == :equal }
+      changed.map { |index| [[index - context, 0].max, [index + context, operations.length - 1].min] }
+             .each_with_object([]) do |(start_index, end_index), ranges|
+        if ranges.last && start_index <= ranges.last.end + 1
+          ranges[-1] = ranges.last.begin..[ranges.last.end, end_index].max
+        else
+          ranges << (start_index..end_index)
+        end
+      end
+    end
+    private_class_method :hunk_ranges
+
+    def append_hunk(output, entries)
+      old_count = entries.count { |entry| entry[:type] != :insert }
+      new_count = entries.count { |entry| entry[:type] != :delete }
+      old_start = entries.first[:old_line] - (old_count.zero? ? 1 : 0)
+      new_start = entries.first[:new_line] - (new_count.zero? ? 1 : 0)
+      output << "@@ -#{range(old_start, old_count)} +#{range(new_start, new_count)} @@\n"
+      entries.each do |entry|
+        marker = { equal: ' ', delete: '-', insert: '+' }.fetch(entry[:type])
+        output << marker << entry[:line]
+        next if entry[:line].end_with?("\n")
+
+        output << "\n\\n"
+      end
+    end
+    private_class_method :append_hunk
+
+    def range(start_line, count)
+      count == 1 ? start_line.to_s : "#{start_line},#{count}"
+    end
+    private_class_method :range
+
+    def validate_options(path, context)
+      if path.to_s.empty? || path.to_s.match?(/[\t\r\n]/)
+        raise ArgumentError, 'path must not be empty or contain control separators'
+      end
+      raise ArgumentError, 'context must be a non-negative integer' unless context.is_a?(Integer) && context >= 0
+    end
+    private_class_method :validate_options
+  end
+
+  module RewriterDiff
+    def to_diff(context: 3, path: @source_file.path)
+      Diff.unified(@source_file.source, rewrite, path: path, context: context)
+    end
+  end
+end
+
+Astel::Rewriter.include(Astel::RewriterDiff)

data/lib/astel/location.rb

@@ -33,5 +33,64 @@ module Astel
     def range
       start_offset...end_offset
     end
+
+    def empty?
+      start_offset == end_offset
+    end
+
+    def contains?(other)
+      other = self.class.from(other)
+      start_offset <= other.start_offset && end_offset >= other.end_offset
+    end
+
+    def overlaps?(other)
+      other = self.class.from(other)
+      start_offset < other.end_offset && other.start_offset < end_offset
+    end
+
+    def join(other)
+      other = self.class.from(other)
+      first = start_offset <= other.start_offset ? self : other
+      last = end_offset >= other.end_offset ? self : other
+      self.class.new(
+        start_offset: first.start_offset,
+        end_offset: last.end_offset,
+        start_line: first.start_line,
+        start_column: first.start_column,
+        end_line: last.end_line,
+        end_column: last.end_column
+      )
+    end
+
+    def adjust(start: 0, **changes)
+      ending = changes.fetch(:end, 0)
+      raise ArgumentError, "unknown keyword: #{changes.keys.first}" unless (changes.keys - [:end]).empty?
+
+      adjusted_start = start_offset + start
+      adjusted_end = end_offset + ending
+      adjusted_start_column = start_column + start
+      adjusted_end_column = end_column + ending
+      if adjusted_start.negative? || adjusted_start > adjusted_end ||
+         adjusted_start_column.negative? || adjusted_end_column.negative?
+        raise RangeError, 'adjusted location is invalid'
+      end
+
+      self.class.new(
+        start_offset: adjusted_start,
+        end_offset: adjusted_end,
+        start_line: start_line,
+        start_column: adjusted_start_column,
+        end_line: end_line,
+        end_column: adjusted_end_column
+      )
+    end
+
+    def begin_point
+      self.class.point(offset: start_offset, line: start_line, column: start_column)
+    end
+
+    def end_point
+      self.class.point(offset: end_offset, line: end_line, column: end_column)
+    end
   end
 end

data/lib/astel/refactor/comments.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Astel
+  module Refactor
+    def leading_comments(node)
+      attach_comments
+      node.location.leading_comments
+    end
+
+    def trailing_comment(node)
+      attach_comments
+      node.location.trailing_comments.first
+    end
+
+    def remove_with_comments(node)
+      comments = leading_comments(node)
+      trailing = trailing_comment(node)
+      start_offset = comments.empty? ? node.location.start_offset : comments.first.location.start_offset
+      end_offset = trailing ? trailing.location.end_offset : node.location.end_offset
+      first = @source_file.line_location(start_offset)
+      last = @source_file.line_location(end_offset - 1)
+      before = @source_file.source.byteslice(first.start_offset, start_offset - first.start_offset)
+      after = @source_file.source.byteslice(end_offset, last.end_offset - end_offset)
+      return remove(start_offset...end_offset) unless before.strip.empty? && after.strip.empty?
+
+      ending = @source_file.line_location_with_newline(end_offset - 1).end_offset
+      remove(first.start_offset...ending)
+    end
+
+    private
+
+    def attach_comments
+      @source_file.attach_comments!
+    end
+  end
+end

data/lib/astel/refactor/formatting.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Astel
+  module Refactor
+    def indentation_of(node)
+      @source_file.indentation_at(node.location.start_offset)
+    end
+
+    def indent(text, level: 1)
+      prefix = @source_file.indent_unit * level
+      text.lines(chomp: false).map { |line| line.strip.empty? ? line : "#{prefix}#{line}" }.join
+    end
+
+    def dedent(text)
+      widths = text.lines.filter_map do |line|
+        next if line.strip.empty?
+
+        line[/\A[ \t]*/].bytesize
+      end
+      width = widths.min || 0
+      text.lines(chomp: false).map { |line| line.strip.empty? ? line : line.byteslice(width..) }.join
+    end
+
+    def reindent(text, to:)
+      prefix = indentation_of(to)
+      dedent(text).lines(chomp: false).map { |line| line.strip.empty? ? line : "#{prefix}#{line}" }.join
+    end
+
+    def insert_into_body(node, source_text, position: :end)
+      statements = body_statements(node)
+      target, after, section_break = body_insertion_target(node, statements, position)
+      first_statement = statements&.body&.first
+      child_indent = if first_statement &&
+                        @source_file.line_at(first_statement.location.start_offset) !=
+                          @source_file.line_at(node.location.start_offset)
+                       indentation_of(first_statement)
+                     else
+                       "#{indentation_of(node)}#{@source_file.indent_unit}"
+                     end
+      content = format_body_source(source_text, child_indent)
+
+      if after
+        line = @source_file.line_location_with_newline(target.location.end_offset - 1)
+        suffix = line_terminated?(line) ? '' : @source_file.newline
+        insert_after(line, "#{suffix}#{content}#{@source_file.newline}")
+      else
+        offset = target ? @source_file.line_start(target.location.start_offset) : body_closing_location(node).start_offset
+        prefix = needs_leading_newline?(offset) ? @source_file.newline : ''
+        suffix = section_break ? @source_file.newline * 2 : @source_file.newline
+        insert_before(offset...offset, "#{prefix}#{content}#{suffix}")
+      end
+    end
+
+    def remove_line(node)
+      location = node.location
+      first = @source_file.line_location(location.start_offset)
+      last_offset = [location.end_offset - 1, location.start_offset].max
+      last = @source_file.line_location(last_offset)
+      before = @source_file.source.byteslice(first.start_offset, location.start_offset - first.start_offset)
+      after = @source_file.source.byteslice(location.end_offset, last.end_offset - location.end_offset)
+      return remove(location) unless before.strip.empty? && after.strip.empty?
+
+      ending = @source_file.line_location_with_newline(last_offset).end_offset
+      remove(first.start_offset...ending)
+    end
+
+    def insert_line_before(node, text)
+      line_start = @source_file.line_start(node.location.start_offset)
+      content = format_body_source(text, indentation_of(node))
+      insert_before(line_start...line_start, "#{content}#{@source_file.newline}")
+    end
+
+    def insert_line_after(node, text)
+      line = @source_file.line_location_with_newline(node.location.end_offset - 1)
+      content = format_body_source(text, indentation_of(node))
+      prefix = line_terminated?(line) ? '' : @source_file.newline
+      insert_after(line, "#{prefix}#{content}#{@source_file.newline}")
+    end
+
+    def comment_out(node)
+      first = @source_file.line_start(node.location.start_offset)
+      last = @source_file.line_end([node.location.end_offset - 1, node.location.start_offset].max)
+      text = @source_file.source.byteslice(first, last - first)
+      commented = text.lines(chomp: false).map do |line|
+        indentation = line[/\A[ \t]*/]
+        "#{indentation}# #{line.delete_prefix(indentation)}"
+      end.join
+      replace(first...last, commented)
+    end
+
+    private
+
+    def body_statements(node)
+      body = node.respond_to?(:body) ? node.body : nil
+      body if body.is_a?(Prism::StatementsNode)
+    end
+
+    def body_closing_location(node)
+      return node.end_keyword_loc if node.respond_to?(:end_keyword_loc) && node.end_keyword_loc
+      return node.closing_loc if node.respond_to?(:closing_loc) && node.closing_loc
+
+      raise ArgumentError, 'node does not have a delimited body'
+    end
+
+    def body_insertion_target(node, statements, position)
+      body = statements&.body || []
+      case position
+      when :beginning then return [body.first, false, false]
+      when :end then return [nil, false, false]
+      when :before_private
+        marker = body.find { |child| visibility_marker?(child) }
+        return [marker, false, !marker.nil?]
+      when Hash
+        return [position.fetch(:after), true, false] if position.key?(:after)
+        return [position.fetch(:before), false, false] if position.key?(:before)
+      end
+      raise ArgumentError, 'unsupported body insertion position'
+    end
+
+    def visibility_marker?(node)
+      node.is_a?(Prism::CallNode) && node.receiver.nil? && node.arguments.nil? &&
+        %i[private protected].include?(node.name)
+    end
+
+    def format_body_source(text, indentation)
+      normalized = dedent(text.to_s).gsub(/\r?\n/, @source_file.newline).delete_suffix(@source_file.newline)
+      normalized.lines(chomp: false).map { |line| line.strip.empty? ? line : "#{indentation}#{line}" }.join
+    end
+
+    def needs_leading_newline?(offset)
+      offset.positive? && ![10, 13].include?(@source_file.source.getbyte(offset - 1))
+    end
+
+    def line_terminated?(location)
+      location.end_offset.positive? && @source_file.source.getbyte(location.end_offset - 1) == 10
+    end
+  end
+end

data/lib/astel/refactor.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require_relative '../astel'
+
+module Astel
+  module Refactor
+    def find_keyword_argument(call_node, name)
+      keyword_hashes(call_node).each do |keyword_hash|
+        match = keyword_hash.elements.find { |element| keyword_name(element) == name.to_sym }
+        return match if match
+      end
+      nil
+    end
+
+    def remove_keyword_argument(call_node, name)
+      argument = find_keyword_argument(call_node, name)
+      return self unless argument
+
+      keyword_hash = keyword_hashes(call_node).find { |hash| hash.elements.include?(argument) }
+      if keyword_hash.elements.one?
+        if call_node.arguments.arguments.one? && !call_node.opening_loc
+          return remove(call_node.message_loc.end_offset...keyword_hash.location.end_offset)
+        end
+        remove_list_element(call_node.arguments, keyword_hash)
+      else
+        remove_list_element(keyword_hash, argument)
+      end
+    end
+
+    def replace_keyword_key(assoc_node, name)
+      replacement = assoc_node.operator_loc ? ":#{name}" : "#{name}:"
+      replace(assoc_node.key.location, replacement)
+    end
+
+    def replace_keyword_value(assoc_node, replacement)
+      replace(assoc_node.value.location, replacement)
+    end
+
+    def insert_keyword_argument(call_node, text, position: :last)
+      raise ArgumentError, 'position must be :first or :last' unless %i[first last].include?(position)
+
+      arguments = call_node.arguments
+      unless arguments
+        location = call_node.opening_loc || call_node.message_loc
+        if call_node.opening_loc && call_node.closing_loc
+          return insert_into_empty_delimited(call_node, text)
+        end
+        return insert_after(location, call_node.opening_loc ? text : " #{text}")
+      end
+
+      keyword_hash = keyword_hashes(call_node).first
+      if keyword_hash
+        index = position == :first ? 0 : keyword_hash.elements.length
+        return insert_list_element(keyword_hash, index, text)
+      end
+
+      index = arguments.arguments.length
+      insert_list_element(arguments, index, text)
+    end
+
+    def remove_list_element(collection_node, element_node)
+      remove_list_elements(collection_node, [element_node])
+    end
+
+    def remove_list_elements(collection_node, element_nodes)
+      elements = collection_elements(collection_node)
+      indexes = element_nodes.map do |element|
+        elements.index { |candidate| candidate.equal?(element) } ||
+          raise(ArgumentError, 'element does not belong to collection')
+      end.uniq.sort
+      return self if indexes.empty?
+
+      trailing_end = trailing_comma_end(elements.last)
+      replacements = deletion_ranges(elements, indexes, trailing_end)
+      start_offset = elements.first.location.start_offset
+      end_offset = trailing_end
+      content = @source_file.source.byteslice(start_offset, end_offset - start_offset).dup
+      replacements.reverse_each do |from, to, replacement|
+        content[(from - start_offset)...(to - start_offset)] = replacement
+      end
+      replace(start_offset...end_offset, content)
+    end
+
+    def insert_list_element(collection_node, index, text)
+      elements = collection_elements(collection_node)
+      raise IndexError, 'list index is outside the collection' unless index.between?(0, elements.length)
+
+      if elements.empty?
+        opening = collection_node.respond_to?(:opening_loc) && collection_node.opening_loc
+        raise ArgumentError, 'cannot locate an empty collection body' unless opening
+
+        return insert_into_empty_delimited(collection_node, text)
+      end
+
+      if index < elements.length
+        target = elements[index]
+        separator = multiline_collection?(collection_node) ? ",#{@source_file.newline}#{indentation_of(target)}" : ', '
+        return insert_before(target.location, "#{text}#{separator}")
+      end
+
+      last = elements.last
+      separator = multiline_collection?(collection_node) ? ",#{@source_file.newline}#{indentation_of(last)}" : ', '
+      insert_after(last.location, "#{separator}#{text}")
+    end
+
+    private
+
+    def keyword_hashes(call_node)
+      call_node.arguments&.arguments&.grep(Prism::KeywordHashNode) || []
+    end
+
+    def keyword_name(assoc_node)
+      key = assoc_node.key
+      key.unescaped.to_sym if key.is_a?(Prism::SymbolNode)
+    end
+
+    def collection_elements(collection_node)
+      case collection_node
+      when Prism::ArgumentsNode then collection_node.arguments
+      when Prism::ArrayNode, Prism::KeywordHashNode, Prism::HashNode then collection_node.elements
+      else
+        raise ArgumentError, 'collection must be an arguments, array, or hash node'
+      end
+    end
+
+    def deletion_ranges(elements, indexes, trailing_end)
+      removed = indexes.to_h { |index| [index, true] }
+      groups = indexes.slice_when { |left, right| right != left + 1 }.to_a
+      groups.map do |group|
+        first = group.first
+        last = group.last
+        following = ((last + 1)...elements.length).find { |index| !removed[index] }
+        preceding = (first - 1).downto(0).find { |index| !removed[index] }
+
+        if following
+          [elements[first].location.start_offset, elements[following].location.start_offset, '']
+        elsif preceding
+          from = elements[preceding].location.end_offset
+          has_trailing_comma = last == elements.length - 1 && trailing_end > elements.last.location.end_offset
+          to = has_trailing_comma ? trailing_end : elements[last].location.end_offset
+          between = @source_file.source.byteslice(from, elements[first].location.start_offset - from)
+          replacement = if has_trailing_comma
+                          between.include?('#') ? between.rstrip : ','
+                        elsif between.include?('#')
+                          between.sub(',', '').rstrip
+                        else
+                          ''
+                        end
+          [from, to, replacement]
+        else
+          [elements.first.location.start_offset, trailing_end, '']
+        end
+      end
+    end
+
+    def trailing_comma_end(element)
+      offset = element.location.end_offset
+      source = @source_file.source
+      offset += 1 while [32, 9].include?(source.getbyte(offset))
+      source.getbyte(offset) == 44 ? offset + 1 : element.location.end_offset
+    end
+
+    def multiline_collection?(collection_node)
+      return true if @source_file.slice(collection_node.location).include?("\n")
+
+      start_offset = collection_node.location.start_offset
+      prefix = @source_file.source.byteslice(@source_file.line_start(start_offset),
+                                             start_offset - @source_file.line_start(start_offset))
+      collection_node.is_a?(Prism::KeywordHashNode) && !prefix.empty? && prefix.strip.empty?
+    end
+
+    def insert_into_empty_delimited(node, text)
+      opening = node.opening_loc
+      closing = node.closing_loc
+      return insert_after(opening, text) unless closing
+
+      source = @source_file.source
+      interior = source.byteslice(opening.end_offset, closing.start_offset - opening.end_offset)
+      return insert_after(opening, text) unless interior.include?("\n")
+
+      indentation = @source_file.indentation_at(closing.start_offset)
+      replacement = "#{@source_file.newline}#{indentation}#{@source_file.indent_unit}#{text}" \
+                    "#{@source_file.newline}#{indentation}"
+      replace(opening.end_offset...closing.start_offset, replacement)
+    end
+  end
+end
+
+require_relative 'refactor/formatting'
+require_relative 'refactor/comments'
+
+Astel::Rewriter.include(Astel::Refactor)

data/lib/astel/rewriter.rb

@@ -13,6 +13,16 @@ module Astel
       end
     end
 
+    class ValidationError < Error
+      attr_reader :result, :parse_errors
+
+      def initialize(result, parse_errors)
+        @result = result
+        @parse_errors = parse_errors.freeze
+        super("rewritten source contains #{parse_errors.length} syntax error(s)")
+      end
+    end
+
     Edit = Data.define(:start_offset, :end_offset, :replacement, :sequence) do
       def insertion?
         start_offset == end_offset
@@ -34,24 +44,22 @@ module Astel
           return
         end
 
-        block_index = block_index_for(edit)
-        block = @blocks.fetch(block_index)
-        edit_index = block.bsearch_index { |existing| ordered_after?(existing, edit) } || block.length
-        following = block[edit_index] || @blocks[block_index + 1]&.first
-        return following if following && yield(following)
-
-        preceding = if edit_index.positive?
-                      block[edit_index - 1]
-                    elsif block_index.positive?
-                      @blocks[block_index - 1].last
-                    end
-        return preceding if preceding && yield(preceding)
+        block_index, block, edit_index = insertion_position(edit)
+        conflict = conflict_at(block_index, block, edit_index) { |existing| yield existing }
+        return conflict if conflict
 
         block.insert(edit_index, edit)
         split(block_index, block) if block.length > SPLIT_THRESHOLD
         nil
       end
 
+      def find_conflict(edit)
+        return if @blocks.empty?
+
+        block_index, block, edit_index = insertion_position(edit)
+        conflict_at(block_index, block, edit_index) { |existing| yield existing }
+      end
+
       def each
         return enum_for(__method__) unless block_given?
 
@@ -62,6 +70,27 @@ module Astel
 
       private
 
+      def insertion_position(edit)
+        block_index = block_index_for(edit)
+        block = @blocks.fetch(block_index)
+        edit_index = block.bsearch_index { |existing| ordered_after?(existing, edit) } || block.length
+        [block_index, block, edit_index]
+      end
+
+      def conflict_at(block_index, block, edit_index)
+        following = block[edit_index] || @blocks[block_index + 1]&.first
+        return following if following && yield(following)
+
+        preceding = if edit_index.positive?
+                      block[edit_index - 1]
+                    elsif block_index.positive?
+                      @blocks[block_index - 1].last
+                    end
+        return preceding if preceding && yield(preceding)
+
+        nil
+      end
+
       def block_index_for(edit)
         @blocks.bsearch_index { |block| ordered_after?(block.last, edit) } || @blocks.length - 1
       end
@@ -79,13 +108,22 @@ module Astel
       end
     end
 
-    def initialize(source_file)
+    attr_reader :source_file
+
+    def initialize(source_file, duplicate_insertions: :accept)
+      unless %i[accept raise].include?(duplicate_insertions)
+        raise ArgumentError, 'duplicate_insertions must be :accept or :raise'
+      end
+
       @source_file = source_file
+      @duplicate_insertions = duplicate_insertions
       @edits = []
       @edits_snapshot = nil
       @edit_index = EditIndex.new
       @sequence = 0
       @result_size_delta = 0
+      @transaction_staging = false
+      @transaction_failed = false
     end
 
     def edits
@@ -111,7 +149,47 @@ module Astel
       replace(location, '')
     end
 
-    def rewrite
+    def wrap(location, before, after)
+      transaction(raise_on_conflict: true) do |rewriter|
+        rewriter.insert_before(location, before)
+        rewriter.insert_after(location, after)
+      end
+      self
+    end
+
+    def merge!(other)
+      unless other.is_a?(Rewriter) && other.source_file.equal?(@source_file)
+        raise ArgumentError, 'cannot merge edits for a different source'
+      end
+
+      validation_index = EditIndex.new
+      @edit_index.each { |edit| validation_index.add(edit) { false } }
+      other.edits.each do |edit|
+        conflict = validation_index.find_conflict(edit) { |existing| conflict?(edit, existing) }
+        raise ConflictError.new(edit, conflict) if conflict
+
+        validation_index.add(edit) { false }
+      end
+      other.edits.each { |edit| add_edit(edit.start_offset, edit.end_offset, edit.replacement) }
+      self
+    end
+
+    def transaction(raise_on_conflict: false)
+      staging = Rewriter.new(@source_file, duplicate_insertions: @duplicate_insertions)
+      staging.instance_variable_set(:@transaction_staging, true)
+      yield staging
+      return transaction_failed if staging.instance_variable_get(:@transaction_failed)
+
+      merge!(staging)
+      true
+    rescue ConflictError
+      @transaction_failed = true if @transaction_staging
+      raise if raise_on_conflict
+
+      false
+    end
+
+    def rewrite(validate: false)
       source = @source_file.source
       result = String.new(capacity: source.bytesize + @result_size_delta, encoding: source.encoding)
       cursor = 0
@@ -123,6 +201,7 @@ module Astel
       end
 
       result << source.byteslice(cursor, source.bytesize - cursor)
+      validate_result(result, validate)
       result
     end
 
@@ -130,10 +209,15 @@ module Astel
 
     def add_edit(start_offset, end_offset, replacement)
       validate_offsets(start_offset, end_offset)
+      replacement = replacement.to_s.dup
+      unless Encoding.compatible?(@source_file.source, replacement)
+        raise Encoding::CompatibilityError,
+              "#{replacement.encoding} replacement is incompatible with #{@source_file.source.encoding} source"
+      end
       edit = Edit.new(
         start_offset: start_offset,
         end_offset: end_offset,
-        replacement: replacement.to_s.dup.freeze,
+        replacement: replacement.freeze,
         sequence: @sequence
       )
       conflict = @edit_index.add(edit) { |existing| conflict?(edit, existing) }
@@ -161,11 +245,26 @@ module Astel
     end
 
     def conflict?(left, right)
-      return left.start_offset == right.start_offset if left.insertion? && right.insertion?
+      if @duplicate_insertions == :raise && left.insertion? && right.insertion?
+        return left.start_offset == right.start_offset
+      end
       return left.start_offset > right.start_offset && left.start_offset < right.end_offset if left.insertion?
       return right.start_offset > left.start_offset && right.start_offset < left.end_offset if right.insertion?
 
       left.start_offset < right.end_offset && right.start_offset < left.end_offset
     end
+
+    def transaction_failed
+      @transaction_failed = true if @transaction_staging
+      false
+    end
+
+    def validate_result(result, validate)
+      return unless validate
+      raise ArgumentError, 'validate must be false or :parse' unless validate == :parse
+
+      parsed = SourceFile.from_string(result, path: @source_file.path, version: @source_file.version)
+      raise ValidationError.new(result, parsed.errors) unless parsed.valid?
+    end
   end
 end

data/lib/astel/source_file.rb

@@ -4,7 +4,7 @@ require 'prism'
 
 module Astel
   class SourceFile
-    attr_reader :path, :source, :ast, :comments, :errors, :parse_result
+    attr_reader :path, :source, :ast, :comments, :errors, :parse_result, :version
 
     def self.parse(path:, version: nil)
       from_string(File.binread(path), path: path, version: version)
@@ -16,9 +16,10 @@ module Astel
 
     def initialize(code, path:, version: nil)
       @path = path.to_s.freeze
+      @version = normalize_version(version).freeze if version
       raw_source = code.dup.freeze
       options = { filepath: @path }
-      options[:version] = normalize_version(version) if version
+      options[:version] = @version if @version
       @parse_result = Prism.parse(raw_source, **options)
       @source = @parse_result.source.source.freeze
       @ast = @parse_result.value
@@ -47,7 +48,7 @@ module Astel
         start_line: 1,
         start_column: 0,
         end_line: 1,
-        end_column: line.delete_suffix("\n").delete_suffix("\r").length
+        end_column: line.delete_suffix("\n").delete_suffix("\r").bytesize
       )
     end
 
@@ -59,8 +60,95 @@ module Astel
       end
     end
 
+    def attach_comments!
+      return self if @comments_attached
+
+      @parse_result.attach_comments!
+      @comments_attached = true
+      self
+    end
+
+    def line_at(byte_offset)
+      validate_offset!(byte_offset)
+      @parse_result.source.line(byte_offset)
+    end
+
+    def column_at(byte_offset)
+      validate_offset!(byte_offset)
+      @parse_result.source.column(byte_offset)
+    end
+
+    def line_start(byte_offset)
+      validate_offset!(byte_offset)
+      @parse_result.source.line_start(byte_offset)
+    end
+
+    def line_end(byte_offset)
+      validate_offset!(byte_offset)
+      ending = @parse_result.source.line_end(byte_offset)
+      ending -= 1 if ending.positive? && source.getbyte(ending - 1) == 10
+      ending -= 1 if ending.positive? && source.getbyte(ending - 1) == 13
+      ending
+    end
+
+    def line_location(byte_offset)
+      location(line_start(byte_offset), line_end(byte_offset))
+    end
+
+    def line_location_with_newline(byte_offset)
+      validate_offset!(byte_offset)
+      location(line_start(byte_offset), @parse_result.source.line_end(byte_offset))
+    end
+
+    def slice(location)
+      source.byteslice(location.start_offset, location.end_offset - location.start_offset)
+    end
+
+    def newline
+      @newline ||= begin
+        crlf = source.b.scan(/\r\n/).length
+        crlf > source.count("\n") - crlf ? "\r\n" : "\n"
+      end
+    end
+
+    def indentation_at(byte_offset)
+      start_offset = line_start(byte_offset)
+      source.byteslice(start_offset, line_end(byte_offset) - start_offset)[/\A[ \t]*/]
+    end
+
+    def indent_unit
+      @indent_unit ||= begin
+        indentations = lines.filter_map { |line| line[/\A[ \t]+/] }
+        if indentations.any? { |indentation| indentation.include?("\t") }
+          "\t"
+        else
+          widths = [0, *indentations.map(&:bytesize)].uniq.sort
+          width = widths.each_cons(2).map { |left, right| right - left }.min
+          width ? ' ' * width : '  '
+        end
+      end
+    end
+
     private
 
+    def location(start_offset, end_offset)
+      prism_source = @parse_result.source
+      Location.new(
+        start_offset: start_offset,
+        end_offset: end_offset,
+        start_line: prism_source.line(start_offset),
+        start_column: prism_source.column(start_offset),
+        end_line: prism_source.line(end_offset),
+        end_column: prism_source.column(end_offset)
+      )
+    end
+
+    def validate_offset!(byte_offset)
+      unless byte_offset.is_a?(Integer) && byte_offset.between?(0, source.bytesize)
+        raise RangeError, 'offset is outside the source'
+      end
+    end
+
     def normalize_version(version)
       version.match?(/\A\d+\.\d+\z/) ? "#{version}.0" : version
     end

data/lib/astel/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Astel
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: astel
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Yudai Takada
@@ -43,7 +43,10 @@ files:
 - benchmark/dispatch_bench.rb
 - benchmark/node_pattern_bench.rb
 - benchmark/rewriter_bench.rb
+- docs/codemod-guide.md
+- docs/refactor.md
 - lib/astel.rb
+- lib/astel/diff.rb
 - lib/astel/dispatcher.rb
 - lib/astel/location.rb
 - lib/astel/node_ext.rb
@@ -53,6 +56,9 @@ files:
 - lib/astel/node_pattern/parser.rb
 - lib/astel/node_pattern/predicate_compiler.rb
 - lib/astel/node_type.rb
+- lib/astel/refactor.rb
+- lib/astel/refactor/comments.rb
+- lib/astel/refactor/formatting.rb
 - lib/astel/rewriter.rb
 - lib/astel/source_file.rb
 - lib/astel/version.rb
@@ -75,7 +81,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Fast Prism AST traversal, matching, and source rewriting
 test_files: []