tree_stand 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d9ecce5098c654a026b3f08bd8e5dc0a87b696d5e56102f11a40540a7b45d72
-  data.tar.gz: 41b5bc8b68fb82183e1d641e735fa9083365c5077402193cbf2128c026b1140e
+  metadata.gz: 957ff5fd108366dc0b3c0ec05c821a8d207930a4ccf291e1092d26e373a0f4da
+  data.tar.gz: fce8cce29e6d558ee447f2afcdf9c83dd276521c0261ec99be93dea8c456b9b1
 SHA512:
-  metadata.gz: e1a91dcfa898f9341ed7d8493204cec0ff1170b157e8598226a41858faa96de9f4df45b6e1e449c5c817b3edc7b44efa9bfb7bbfae6a1f4a031580ff0663a0e3
-  data.tar.gz: 23cc338e725309b833f1b9200101f191772798e3a85d1610c41237522096a7454013fcf6252de8b161c62f7831a263f2ec94603aff4be47739b4a78cc4fdcedc
+  metadata.gz: 0f87824f3b009cb8d6993e25cd9b44c2ba645bcf253ef88771b12307a37190a8cb3e405836baea363344763c71cfd3be1bf5c53dd10c69bdfbd66fad1dfdd62d
+  data.tar.gz: 25b6b852ff81d122a61d8c74fa94e2e4cde20918ca1b0323b7dbda2e30666d534c8f4acaf736c5298b1de09a6491a819f44badeab3d2ec0a13c56a5e9e46c7ef

data/.gitattributes

@@ -0,0 +1 @@
+sorbet/rbi/** linguist-generated

data/.github/workflows/ci.yml

@@ -15,15 +15,11 @@ jobs:
         entry:
           - { ruby: 3.0 }
           - { ruby: 3.1 }
+          - { ruby: 3.2 }
     name: test (${{ matrix.entry.ruby }})
     steps:
       - uses: actions/checkout@v3
 
-      - uses: actions/checkout@v3
-        with:
-          repository: DerekStride/tree-sitter-sql
-          path: tmp/tree-sitter-sql
-
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.entry.ruby }}
@@ -33,12 +29,8 @@ jobs:
           key: ${{ runner.os }}-gems-${{ hashFiles('Gemfile') }}
           restore-keys: ${{ runner.os }}-gems-
 
-      - uses: actions/setup-node@v3
-        with:
-          node-version: 16
-      - run: npm install tree-sitter-cli
-
-      - run: sudo apt-get install -y libtree-sitter-dev make gcc
+      - run: sudo apt-get install -y libtree-sitter-dev
       - run: bundle install --jobs=3 --retry=3 --path=vendor/bundle
       - run: bin/setup
+      - run: bundle exec srb tc
       - run: bundle exec rake

data/.yardopts

@@ -0,0 +1,6 @@
+--plugin sorbet
+-
+README.md
+CONTRIBUTING.md
+CODE_OF_CONDUCT.md
+LICENSE.txt

data/CONTRIBUTING.md

@@ -19,6 +19,12 @@ bin/setup
 bundle exec rake test
 ```
 
+### Typechecking
+
+```
+bundle exec srb tc
+```
+
 ### Documentation
 
 To run the documentation server, execute the following command and open [localhost:8808](http://localhost:8808).

data/Gemfile

@@ -2,4 +2,16 @@ source "https://rubygems.org"
 
 gemspec
 
-gem 'tree_sitter', git: 'https://github.com/Faveod/ruby-tree-sitter'
+group :development, :test do
+  gem "bundler", "~> 2.3"
+  gem "debug", "~> 1.7", require: false
+  gem "rake", "~> 13.0"
+  gem 'tapioca', "~> 0.11.1", require: false
+  gem "yard", "~> 0.9.28"
+end
+
+group :test do
+  gem "minitest", "~> 5.17"
+  gem "minitest-reporters", "~> 1.5"
+  gem "minitest-focus", "~> 1.3"
+end

data/README.md

@@ -20,7 +20,7 @@ See the [documentation](https://shopify.github.io/tree_stand) for supported feat
 
 ### Setting Up a Parser
 
-TreeStand do not help with compiling individual parsers. However, once you compile a parser and generate a shared
+TreeStand does not help with compiling individual parsers. However, once you compile a parser and generate a shared
 object (`.so`) or a dynamic library (`.dylib`) you can tell TreeStand where to find them and pass the parser filename
 to `TreeStand::Parser::new`.
 
@@ -48,10 +48,12 @@ The underlying objects are accessible via a `ts_` prefixed attribute, e.g. `ts_p
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/Shopify/tree_stand. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
+See [CONTRIBUTING.md](https://github.com/Shopify/tree_stand/blob/main/CONTRIBUTING.md) for documentation on how to set up the project for development.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ## Code of Conduct
 
-Everyone interacting in the TreeStand project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/Shopify/tree_stand/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the TreeStand project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/Shopify/tree_stand/blob/main/CODE_OF_CONDUCT.md).

data/bin/console

@@ -11,12 +11,12 @@ end
 
 ivars_to_add = <<~RUBY
   @parser = TreeStand::Parser.new("math")
-  @tree = @parser.parse_string(nil, "1 + x")
+  @tree = @parser.parse_string("1 + x")
 RUBY
 
 eval(ivars_to_add)
 puts("available ivars:")
 puts(ivars_to_add)
 
-require "pry"
-Pry.start
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -13,7 +13,6 @@ fi
 
 cd tmp/tree-sitter-math
 
-npm install
 mkdir -p target
 gcc -shared -o target/parser.so -fPIC src/parser.c -I./src
 

data/bin/tapioca

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'tapioca' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("tapioca", "tapioca")

data/lib/tree_stand/ast_modifier.rb

@@ -1,10 +1,15 @@
+# frozen_string_literal: true
+# typed: true
+
 module TreeStand
-  # An experimental class to modify the AST. I re-runs the query on the
+  # An experimental class to modify the AST. It re-runs the query on the
   # modified document every loop to ensure that the match is still valid.
   # @see TreeStand::Tree
   # @api experimental
   class AstModifier
-    # @param tree [TreeStand::Tree]
+    extend T::Sig
+
+    sig { params(tree: TreeStand::Tree).void }
     def initialize(tree)
       @tree = tree
     end

data/lib/tree_stand/config.rb

@@ -1,8 +1,13 @@
+# frozen_string_literal: true
+# typed: true
+
 module TreeStand
   # Global configuration for the gem.
   # @api private
   class Config
-    # @return [String]
+    extend T::Sig
+
+    sig { returns(String) }
     attr_accessor :parser_path
   end
 end

data/lib/tree_stand/node.rb

@@ -1,9 +1,13 @@
+# frozen_string_literal: true
+# typed: true
+
 module TreeStand
   # Wrapper around a TreeSitter node and provides convient
   # methods that are missing on the original node. This class
   # overrides the `method_missing` method to delegate to a nodes
   # named children.
   class Node
+    extend T::Sig
     extend Forwardable
     include Enumerable
 
@@ -17,20 +21,13 @@ module TreeStand
       :error?,
     )
 
-    # @return [TreeStand::Tree]
+    sig { returns(TreeStand::Tree) }
     attr_reader :tree
-    # @return [TreeSitter::Node]
+    sig { returns(TreeSitter::Node) }
     attr_reader :ts_node
 
-    # @!method to_a
-    #   @example
-    #     node.text # => "3 * 4"
-    #     node.to_a.map(&:text) # => ["3", "*", "4"]
-    #     node.children.map(&:text) # => ["3", "*", "4"]
-    #   @return [Array<TreeStand::Node>]
-    alias_method :children, :to_a
-
     # @api private
+    sig { params(tree: TreeStand::Tree, ts_node: TreeSitter::Node).void }
     def initialize(tree, ts_node)
       @tree = tree
       @ts_node = ts_node
@@ -53,9 +50,7 @@ module TreeStand
     #   tree.root_node.query(<<~QUERY)
     #     (identifier) @identifier
     #   QUERY
-    #
-    # @param query_string [String]
-    # @return [Array<Hash<String, TreeStand::Node>>]
+    sig { params(query_string: String).returns(T::Array[T::Hash[String, TreeStand::Node]]) }
     def query(query_string)
       ts_query = TreeSitter::Query.new(@tree.parser.ts_language, query_string)
       ts_cursor = TreeSitter::QueryCursor.exec(ts_query, ts_node)
@@ -81,8 +76,7 @@ module TreeStand
     #
     # @see #find_node!
     # @see #query
-    # @param query_string [String]
-    # @return [TreeStand::Node, nil]
+    sig { params(query_string: String).returns(T.nilable(TreeStand::Node)) }
     def find_node(query_string)
       query(query_string).first&.values&.first
     end
@@ -91,14 +85,13 @@ module TreeStand
     # {TreeStand::NodeNotFound} error.
     #
     # @see #find_node
-    # @param query_string [String]
-    # @return [TreeStand::Node]
     # @raise [TreeStand::NodeNotFound]
+    sig { params(query_string: String).returns(TreeStand::Node) }
     def find_node!(query_string)
       find_node(query_string) || raise(TreeStand::NodeNotFound)
     end
 
-    # @return [TreeStand::Range]
+    sig { returns(TreeStand::Range) }
     def range
       TreeStand::Range.new(
         start_byte: @ts_node.start_byte,
@@ -122,13 +115,19 @@ module TreeStand
     #   node.map(&:text) # => ["3", "*", "4"]
     #
     # @yieldparam child [TreeStand::Node]
-    # @return [Enumerator]
+    sig do
+      override
+        .params(block: T.nilable(T.proc.params(node: TreeStand::Node).returns(BasicObject)))
+        .returns(T::Enumerator[TreeStand::Node])
+    end
     def each(&block)
-      Enumerator.new do |yielder|
+      enumerator = Enumerator.new do |yielder|
         @ts_node.each do |child|
           yielder << TreeStand::Node.new(@tree, child)
         end
-      end.each(&block)
+      end
+      enumerator.each(&block) if block_given?
+      enumerator
     end
 
     # (see TreeStand::Visitors::TreeWalker)
@@ -137,32 +136,44 @@ module TreeStand
     # @example Check the subtree for error nodes
     #   node.walk.any? { |node| node.type == :error }
     #
-    # @yieldparam node [TreeStand::Node]
-    # @return [Enumerator]
-    #
     # @see TreeStand::Visitors::TreeWalker
+    #
+    # @yieldparam node [TreeStand::Node]
+    sig do
+      params(block: T.nilable(T.proc.params(node: TreeStand::Node).returns(BasicObject)))
+        .returns(T::Enumerator[TreeStand::Node])
+    end
     def walk(&block)
-      Enumerator.new do |yielder|
+      enumerator = Enumerator.new do |yielder|
         Visitors::TreeWalker.new(self) do |child|
           yielder << child
         end.visit
-      end.each(&block)
+      end
+      enumerator.each(&block) if block_given?
+      enumerator
     end
 
     # @example
     #   node.text # => "4"
     #   node.parent.text # => "3 * 4"
     #   node.parent.parent.text # => "1 + 3 * 4"
-    # @return [TreeStand::Node]
+    sig { returns(TreeStand::Node) }
     def parent
       TreeStand::Node.new(@tree, @ts_node.parent)
     end
 
-    # A convience method for getting the text of the node. Each {TreeStand::Node}
+    # @example
+    #   node.text # => "3 * 4"
+    #   node.to_a.map(&:text) # => ["3", "*", "4"]
+    #   node.children.map(&:text) # => ["3", "*", "4"]
+    sig { returns(T::Array[TreeStand::Node]) }
+    def children = to_a
+
+    # A convenience method for getting the text of the node. Each {TreeStand::Node}
     # wraps the parent {TreeStand::Tree #tree} and has access to the source document.
-    # @return [String]
+    sig { returns(String) }
     def text
-      @tree.document[@ts_node.start_byte...@ts_node.end_byte]
+      T.must(@tree.document[@ts_node.start_byte...@ts_node.end_byte])
     end
 
     # This class overrides the `method_missing` method to delegate to the
@@ -183,26 +194,21 @@ module TreeStand
     #   @raise [NoMethodError]
     def method_missing(method, *args, &block)
       return super unless @fields.include?(method.to_s)
-      TreeStand::Node.new(@tree, @ts_node.public_send(method, *args, &block))
+      TreeStand::Node.new(@tree, T.unsafe(@ts_node).public_send(method, *args, &block))
     end
 
-    # @param other [Object]
-    # @return [bool]
+    sig { params(other: Object).returns(T::Boolean) }
     def ==(other)
       return false unless other.is_a?(TreeStand::Node)
 
-      range == other.range &&
-        type == other.type &&
-        text == other.text
+      T.must(range == other.range && type == other.type && text == other.text)
     end
 
     # (see TreeStand::Utils::Printer)
     # Backed by {TreeStand::Utils::Printer}.
     #
-    # @param pp [PP]
-    # @return [void]
-    #
     # @see TreeStand::Utils::Printer
+    sig { params(pp: PP).void }
     def pretty_print(pp)
       Utils::Printer.new(ralign: 80).print(self, io: pp.output)
     end

data/lib/tree_stand/parser.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+# typed: true
+
 module TreeStand
   # Wrapper around the TreeSitter parser. It looks up the parser by filename in
   # the configured parsers directory.
@@ -12,12 +15,15 @@ module TreeStand
   #   # Looks for a parser in `path/to/parser/folder/ruby.{so,dylib}`
   #   ruby_parser = TreeStand::Parser.new("ruby")
   class Parser
-    # @return [TreeSitter::Language]
+    extend T::Sig
+
+    sig { returns(TreeSitter::Language) }
     attr_reader :ts_language
-    # @return [TreeSitter::Parser]
+    sig { returns(TreeSitter::Parser) }
     attr_reader :ts_parser
 
     # @param language [String]
+    sig { params(language: String).void }
     def initialize(language)
       @language_string = language
       @ts_language = TreeSitter::Language.load(
@@ -33,8 +39,7 @@ module TreeStand
     # @param tree [TreeStand::Tree, nil] providing the old tree will allow the
     #   parser to take advantage of incremental parsing and improve performance
     #   by re-useing nodes from the old tree.
-    # @param document [String]
-    # @return [TreeStand::Tree]
+    sig { params(document: String, tree: T.nilable(TreeStand::Tree)).returns(TreeStand::Tree) }
     def parse_string(document, tree: nil)
       # @todo There's a bug with passing a non-nil tree
       ts_tree = @ts_parser.parse_string(nil, document)
@@ -47,6 +52,7 @@ module TreeStand
     #
     # @see #parse_string
     # @raise [TreeStand::InvalidDocument]
+    sig { params(document: String, tree: T.nilable(TreeStand::Tree)).returns(TreeStand::Tree) }
     def parse_string!(document, tree: nil)
       tree = parse_string(document, tree: tree)
       return tree unless tree.any?(&:error?)

data/lib/tree_stand/range.rb

@@ -1,6 +1,11 @@
+# frozen_string_literal: true
+# typed: true
+
 module TreeStand
   # Wrapper around a TreeSitter range. This is mainly used to compare ranges.
   class Range
+    extend T::Sig
+
     # Point is a Struct containing the row and column from a TreeSitter point.
     # TreeStand uses this to compare points.
     # @!attribute [rw] row
@@ -9,16 +14,24 @@ module TreeStand
     #   @return [Integer]
     Point = Struct.new(:row, :column)
 
-    # @return [Integer]
+    sig { returns(Integer) }
     attr_reader :start_byte
-    # @return [Integer]
+    sig { returns(Integer) }
     attr_reader :end_byte
-    # @return [TreeStand::Range::Point]
+    sig { returns(TreeStand::Range::Point) }
     attr_reader  :start_point
-    # @return [TreeStand::Range::Point]
+    sig { returns(TreeStand::Range::Point) }
     attr_reader  :end_point
 
     # @api private
+    sig do
+      params(
+        start_byte: Integer,
+        end_byte: Integer,
+        start_point: T.any(TreeStand::Range::Point, TreeSitter::Point),
+        end_point: T.any(TreeStand::Range::Point, TreeSitter::Point),
+      ).void
+    end
     def initialize(start_byte:, end_byte:, start_point:, end_point:)
       @start_byte = start_byte
       @end_byte = end_byte
@@ -26,8 +39,7 @@ module TreeStand
       @end_point = Point.new(end_point.row, end_point.column)
     end
 
-    # @param other [Object]
-    # @return [bool]
+    sig { params(other: Object).returns(T::Boolean) }
     def ==(other)
       return false unless other.is_a?(TreeStand::Range)
 

data/lib/tree_stand/tree.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+# typed: true
+
 module TreeStand
   # Wrapper around a TreeSitter tree.
   #
@@ -22,25 +25,29 @@ module TreeStand
   # This is not always possible and depends on the edits you make, beware that
   # the tree will be different after each edit and this approach may cause bugs.
   class Tree
+    extend T::Sig
     extend Forwardable
     include Enumerable
 
-    # @return [String]
+    sig { returns(String) }
     attr_reader :document
-    # @return [TreeSitter::Tree]
+    sig { returns(TreeSitter::Tree) }
     attr_reader :ts_tree
-    # @return [TreeStand::Parser]
+    sig { returns(TreeStand::Parser) }
     attr_reader :parser
 
     # @!method query(query_string)
+    #   (see TreeStand::Node#query)
     #   @note This is a convenience method that calls {TreeStand::Node#query} on
     #     {#root_node}.
     #
     # @!method find_node(query_string)
+    #   (see TreeStand::Node#find_node)
     #   @note This is a convenience method that calls {TreeStand::Node#find_node} on
     #     {#root_node}.
     #
     # @!method find_node!(query_string)
+    #   (see TreeStand::Node#find_node!)
     #   @note This is a convenience method that calls {TreeStand::Node#find_node!} on
     #     {#root_node}.
     #
@@ -69,13 +76,14 @@ module TreeStand
     alias_method :each, :walk
 
     # @api private
+    sig { params(parser: TreeStand::Parser, tree: TreeSitter::Tree, document: String).void }
     def initialize(parser, tree, document)
       @parser = parser
       @ts_tree = tree
       @document = document
     end
 
-    # @return [TreeStand::Node]
+    sig { returns(TreeStand::Node) }
     def root_node
       TreeStand::Node.new(self, @ts_tree.root_node)
     end
@@ -83,9 +91,7 @@ module TreeStand
     # This method replaces the section of the document specified by range and
     # replaces it with the provided text. Then it will reparse the document and
     # update the tree!
-    # @param range [TreeStand::Range]
-    # @param replacement [String]
-    # @return [void]
+    sig { params(range: TreeStand::Range, replacement: String).void }
     def edit!(range, replacement)
       new_document = +""
       new_document << @document[0...range.start_byte]
@@ -96,8 +102,7 @@ module TreeStand
 
     # This method deletes the section of the document specified by range. Then
     # it will reparse the document and update the tree!
-    # @param range [TreeStand::Range]
-    # @return [void]
+    sig { params(range: TreeStand::Range).void }
     def delete!(range)
       new_document = +""
       new_document << @document[0...range.start_byte]

data/lib/tree_stand/utils/printer.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+# typed: true
+
 module TreeStand
   # A collection of useful methods for working with syntax trees.
   module Utils
@@ -11,26 +14,26 @@ module TreeStand
     #   #   ("+")                       | +
     #   #   right: (variable)))         | x
     class Printer
-      # @param ralign [Integer] the right alignment for the text column.
+      extend T::Sig
+
+      # @param ralign the right alignment for the text column.
+      sig { params(ralign: Integer).void }
       def initialize(ralign:)
         @ralign = ralign
       end
 
       # (see TreeStand::Utils::Printer)
-      #
-      # @param node [TreeStand::Node]
-      # @param io [IO]
-      # @return [IO]
+      sig { params(node: TreeStand::Node, io: T.any(IO, StringIO, String)).returns(T.any(IO, StringIO, String)) }
       def print(node, io: StringIO.new)
         lines = pretty_output_lines(node)
 
         lines.each do |line|
           if line.text.empty?
-            io.puts line.sexpr
+            io << line.sexpr << "\n"
             next
           end
 
-          io.puts "#{line.sexpr}#{" " * (@ralign - line.sexpr.size)}| #{line.text}"
+          io << "#{line.sexpr}#{" " * (@ralign - line.sexpr.size)}| #{line.text}\n"
         end
 
         io
@@ -48,7 +51,7 @@ module TreeStand
           return [Line.new("#{indent}#{prefix}#{ts_node}", node.text)]
         end
 
-        lines = [Line.new("#{indent}#{prefix}(#{ts_node.type}", "")]
+        lines = T.let([Line.new("#{indent}#{prefix}(#{ts_node.type}", "")], T::Array[Line])
 
         node.each.with_index do |child, index|
           lines += if field_name = ts_node.field_name_for_child(index)
@@ -62,7 +65,7 @@ module TreeStand
           end
         end
 
-        lines.last.sexpr << ")"
+        T.must(lines.last).sexpr << ")"
         lines
       end
     end

data/lib/tree_stand/version.rb

@@ -1,4 +1,7 @@
+# frozen_string_literal: true
+# typed: strong
+
 module TreeStand
   # The current version of the gem.
-  VERSION = "0.1.6"
+  VERSION = "0.2.0"
 end