Enable reusable Prism parse result

Follow-up to Shopify/ruby-lsp#1849.

This feature utilizes ruby/prism#3478 to implement Shopify/ruby-lsp#1849.

By using ruby/prism#3478, this feature enables performance improvements by reusing Prism's parsed results
instead of parsing the source code. Below is a sample code snippet, which is expected to improve performance by
1.3x in this case.

```ruby
#!/usr/local/bin/ruby

require 'benchmark/ips'
require 'prism'
require 'rubocop-ast'

@source = File.read(__FILE__)
@parse_lex_result = Prism.parse_lex(@source)

def build_processed_source(parse_lex_result)
  RuboCop::AST::ProcessedSource.new(
    @source,
    3.4,
    __FILE__,
    parser_engine: 'parser_prism',
    prism_result: parse_lex_result
  )
end

Benchmark.ips do |x|
  x.report('source')                { build_processed_source(nil) }
  x.report('Prism::ParseLexResult') { build_processed_source(@parse_lex_result) }

  x.compare!
end
```

```console
$ bundle exec ruby reusable_ast.rb
ruby 3.4.2 (2025-02-15 revision d2930f8e7a) +PRISM [x86_64-darwin23]
Warming up --------------------------------------
              source   116.000 i/100ms
Prism::ParseLexResult
                       151.000 i/100ms
Calculating -------------------------------------
              source      1.144k (± 8.4%) i/s -      5.684k in   5.018270s
Prism::ParseLexResult
                          1.460k (± 5.2%) i/s -      7.399k in   5.082102s

Comparison:
Prism::ParseLexResult:     1460.3 i/s
              source:     1144.4 i/s - 1.28x  slower
```

Achieving 1.3x speedup with such this simple modification is a significant improvement for Ruby LSP and its users.

## Compatibility

By using `parser_class.instance_method(:initialize).parameters.assoc(:key)`,
the implementation checks whether `Prism#initialize` supports the `:parser` keyword.
If it does not, the system falls back to the conventional parsing method.
This ensures backward compatibility with previous versions of Prism.

## Development Notes

Since this feature is specifically designed for Prism, the keyword name `prism_result` is meant for Prism.
While it may be possible to achieve similar functionality with the Parser gem, there are currently no concrete use cases.
Therefore, for clarity, we have chosen `prism_result` as the keyword.

Additionally, Prism has two types of results: `Prism::ParseResult` and `Prism::ParseLexResult`,
but the `prism_result` keyword argument is meant to receive `Prism::ParseLexResult`.
Since `prism_parse_lex_result` would be too long, the name `prism_result` was chosen to align with the superclass `Prism::Result`.

Author: koic

changelog/new_enable_reusable_prism_parse_result.md

@@ -0,0 +1 @@
+* [#359](https://github.com/rubocop/rubocop-ast/pull/359): Enable reusable Prism parse result. ([@koic][])

lib/rubocop/ast/processed_source.rb

@@ -4,6 +4,27 @@
 
 module RuboCop
   module AST
+    # A `Prism` interface's class that provides a fixed `Prism::ParseLexResult` instead of parsing.
+    #
+    # This class implements the `parse_lex` method to return a preparsed `Prism::ParseLexResult`
+    # rather than parsing the source code. It is useful in use cases like Ruby LSP,
+    # where parsed results are reused across multiple language servers, improving performance.
+    class PrismPreparsed
+      def initialize(prism_result)
+        unless prism_result.is_a?(Prism::ParseLexResult)
+          raise ArgumentError, <<~MESSAGE
+            Expected a `Prism::ParseLexResult` object, but received `#{prism_result.class}`.
+          MESSAGE
+        end
+
+        @prism_result = prism_result
+      end
+
+      def parse_lex(_source, **_options)
+        @prism_result
+      end
+    end
+
     # ProcessedSource contains objects which are generated by Parser
     # and other information such as disabled lines for cops.
     # It also provides a convenient way to access source lines.
@@ -25,7 +46,9 @@ def self.from_file(path, ruby_version, parser_engine: :parser_whitequark)
         new(file, ruby_version, path, parser_engine: parser_engine)
       end
 
-      def initialize(source, ruby_version, path = nil, parser_engine: :parser_whitequark)
+      def initialize(
+        source, ruby_version, path = nil, parser_engine: :parser_whitequark, prism_result: nil
+      )
         parser_engine = parser_engine.to_sym
         unless PARSER_ENGINES.include?(parser_engine)
           raise ArgumentError, 'The keyword argument `parser_engine` accepts `parser_whitequark` ' \
@@ -44,7 +67,7 @@ def initialize(source, ruby_version, path = nil, parser_engine: :parser_whitequa
         @parser_engine = parser_engine
         @parser_error = nil
 
-        parse(source, ruby_version, parser_engine)
+        parse(source, ruby_version, parser_engine, prism_result)
       end
 
       def ast_with_comments
@@ -202,7 +225,7 @@ def comment_index
         end
       end
 
-      def parse(source, ruby_version, parser_engine)
+      def parse(source, ruby_version, parser_engine, prism_result)
         buffer_name = @path || STRING_SOURCE_NAME
         @buffer = Parser::Source::Buffer.new(buffer_name, 1)
 
@@ -216,7 +239,9 @@ def parse(source, ruby_version, parser_engine)
           return
         end
 
-        @ast, @comments, @tokens = tokenize(create_parser(ruby_version, parser_engine))
+        parser = create_parser(ruby_version, parser_engine, prism_result)
+
+        @ast, @comments, @tokens = tokenize(parser)
       end
 
       def tokenize(parser)
@@ -326,10 +351,28 @@ def require_prism_translation_parser(version)
         exit!
       end
 
-      def create_parser(ruby_version, parser_engine)
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def create_parser(ruby_version, parser_engine, prism_result)
         builder = RuboCop::AST::Builder.new
 
-        parser_class(ruby_version, parser_engine).new(builder).tap do |parser|
+        parser_class = parser_class(ruby_version, parser_engine)
+
+        # NOTE: Check if the `Prism#initialize` method has the `:parser` keyword argument.
+        # The `:parser` keyword argument cannot be used to switch parsers because older versions of
+        # Prism do not support it.
+        parser_switch_available = parser_class.instance_method(:initialize).parameters.assoc(:key)
+
+        parser_instance = if prism_result && parser_switch_available
+                            # NOTE: Since it is intended for use with Ruby LSP, it targets only Prism.
+                            # If there is no reuse of a pre-parsed result, such as in Ruby LSP,
+                            # regular parsing with Prism occurs, and `else` branch will be executed.
+                            prism_proxy = PrismPreparsed.new(prism_result)
+                            parser_class.new(builder, parser: prism_proxy)
+                          else
+                            parser_class.new(builder)
+                          end
+
+        parser_instance.tap do |parser|
           # On JRuby there's a risk that we hang in tokenize() if we
           # don't set the all errors as fatal flag. The problem is caused by a bug
           # in Racc that is discussed in issue #93 of the whitequark/parser
@@ -341,6 +384,7 @@ def create_parser(ruby_version, parser_engine)
           end
         end
       end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
       def first_token_index(range_or_node)
         begin_pos = source_range(range_or_node).begin_pos

spec/rubocop/ast/processed_source_spec.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
+require 'prism'
+
 RSpec.describe RuboCop::AST::ProcessedSource do
   subject(:processed_source) do
-    described_class.new(source, ruby_version, path, parser_engine: parser_engine)
+    described_class.new(
+      source, ruby_version, path, parser_engine: parser_engine, prism_result: prism_result
+    )
   end
 
   let(:source) { <<~RUBY }
@@ -12,6 +16,9 @@ def some_method
     end
     some_method
   RUBY
+  let(:prism_result) { nil }
+  let(:prism_parse_lex_result) { Prism.parse_lex(source) }
+
   let(:ast) { processed_source.ast }
   let(:path) { 'ast/and_node_spec.rb' }
 
@@ -59,6 +66,16 @@ def some_method
 
       it_behaves_like 'invalid parser_engine'
     end
+
+    context 'when using `parser_engine: :parser_prism` and `prism_result` with a `ParseLexResult`' do
+      let(:ruby_version) { 3.4 }
+      let(:parser_prism) { :parser_prism }
+      let(:prism_result) { prism_parse_lex_result }
+
+      it 'returns an instance of ProcessedSource' do
+        is_expected.to be_a(described_class)
+      end
+    end
   end
 
   describe '.from_file' do
@@ -94,18 +111,48 @@ def some_method
     it 'is the path passed to .new' do
       expect(processed_source.path).to eq(path)
     end
+
+    context 'when using `parser_engine: :parser_prism` and `prism_result` with a `ParseLexResult`' do
+      let(:ruby_version) { 3.4 }
+      let(:parser_engine) { :parser_prism }
+      let(:prism_result) { prism_parse_lex_result }
+
+      it 'is the path passed to .new' do
+        expect(processed_source.path).to eq(path)
+      end
+    end
   end
 
   describe '#buffer' do
     it 'is a source buffer' do
       expect(processed_source.buffer).to be_a(Parser::Source::Buffer)
     end
+
+    context 'when using `parser_engine: :parser_prism` and `prism_result` with a `ParseLexResult`' do
+      let(:ruby_version) { 3.4 }
+      let(:parser_engine) { :parser_prism }
+      let(:prism_result) { prism_parse_lex_result }
+
+      it 'is a source buffer' do
+        expect(processed_source.buffer).to be_a(Parser::Source::Buffer)
+      end
+    end
   end
 
   describe '#ast' do
     it 'is the root node of AST' do
       expect(processed_source.ast).to be_a(RuboCop::AST::Node)
     end
+
+    context 'when using `parser_engine: :parser_prism` and `prism_result` with a `ParseLexResult`' do
+      let(:ruby_version) { 3.4 }
+      let(:parser_engine) { :parser_prism }
+      let(:prism_result) { prism_parse_lex_result }
+
+      it 'is the root node of AST' do
+        expect(processed_source.ast).to be_a(RuboCop::AST::Node)
+      end
+    end
   end
 
   describe '#comments' do