tree_stand 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 736381046f8ec987fd106632c34cfbcf79055801d19c519d59980da52d9ebf6a
+  data.tar.gz: 7e1563ffb2af294542d3ac35fd287738bae0ebb69f7312907c18b5ff07fafd64
+SHA512:
+  metadata.gz: 36c90d3233c617abb88bb364cd79bc8fc0465301ef91dd0f9043cbc390d7e7ea5bf7f6ddf07ce4d82f715fd6dc2f76a3c3886a601610c29ddd6679effe2aa3f9
+  data.tar.gz: 3ffc48adac74e5623244e0024534c867f074715d03640f7a428b077556e71f5d5b9b9394ad6f02c586b76768878f13511f3772fa70a5871d9fedea537eca6f67

data/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: TreeStand
+on:
+  push:
+    branches:
+      - "main"
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    branches:
+      - 'main'
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        entry:
+          - { ruby: 3.0 }
+          - { ruby: 3.1 }
+    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 }}
+      - uses: actions/cache@v1
+        with:
+          path: vendor/bundle
+          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: bundle install --jobs=3 --retry=3 --path=vendor/bundle
+      - run: bin/setup
+      - run: bundle exec rake

data/.github/workflows/cla.yml

@@ -0,0 +1,22 @@
+name: Contributor License Agreement (CLA)
+
+on:
+  pull_request_target:
+    types: [opened, synchronize]
+  issue_comment:
+    types: [created]
+
+jobs:
+  cla:
+    runs-on: ubuntu-latest
+    if: |
+      (github.event.issue.pull_request
+        && !github.event.issue.pull_request.merged_at
+        && contains(github.event.comment.body, 'signed')
+      )
+      || (github.event.pull_request && !github.event.pull_request.merged)
+    steps:
+      - uses: Shopify/shopify-cla-action@v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          cla-token: ${{ secrets.CLA_TOKEN }}

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/parsers/
+Gemfile.lock

data/.shopify-build/VERSION

@@ -0,0 +1 @@
+v1

data/.shopify-build/tree-stand-publish-package.yml

@@ -0,0 +1,23 @@
+containers:
+  default:
+    build:
+      from: ubuntu-latest
+      type: ci
+      ruby: 3.1
+      rust: stable
+
+steps:
+  - label: Publish Gem
+    timeout: 30m
+    run:
+      - cargo install tree-sitter-cli
+      - tree-sitter -V
+      - mkdir -p tmp
+      - cd tmp
+      - git clone --depth=1 https://github.com/tree-sitter/tree-sitter.git
+      - cd tree-sitter
+      - make
+      - make install
+      - cd ../..
+      - publish:
+          type: gem

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,134 @@
+# Contributor Covenant Code of Conduct
+
+Contact: opensource@shopify.com
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/Gemfile

@@ -0,0 +1,14 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem 'tree_sitter', git: 'https://github.com/Faveod/ruby-tree-sitter'
+
+group :development do
+  gem "yard"
+end
+
+group :test do
+  gem "minitest-focus"
+  gem "minitest-reporters"
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 derekstride
+
+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,54 @@
+# TreeStand
+
+[![TreeStand](https://github.com/Shopify/tree_stand/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Shopify/tree_stand/actions/workflows/ci.yml)
+
+
+TreeStand is a high-level Ruby wrapper for the [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) bindings. It
+makes it easier to configure the parsers, and work with the underlying syntax tree.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "tree_stand"
+```
+
+## Usage
+
+### Setting Up a Parser
+
+TreeStand do 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`.
+
+```ruby
+TreeStand.configure do
+  config.parser_path = "path/to/parser/folder/"
+end
+
+sql_parser = TreeStand::Parser.new("sql")
+ruby_parser = TreeStand::Parser.new("ruby")
+```
+
+
+### API Conventions
+
+TreeStand aims to provide APIs similar to TreeSitter when possible. For example, the TreeSitter parser exposes a
+`#parse_string(tree, document)` method. TreeStand replicates this behaviour but augments it to return a
+`TreeStand::Tree` instead of the underlying `TreeSitter::Tree`. Similarly, `TreeStand::Tree#root_node` returns a
+`TreeStand::Node` & `TreeSitter::Tree#root_node` returns a `TreeSitter::Node`.
+
+The underlying objects are accessible via a `ts_` prefixed attribute, e.g. `ts_parser`, `ts_tree`, `ts_node`, etc.
+
+## Contributing
+
+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.
+
+## 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).

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib' << 'test'
+  t.pattern = 'test/**/*_test.rb'
+end
+
+task default: :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "tree_stand"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here
+if [[ ! -d tmp/tree-sitter-sql ]]; then
+  mkdir -p tmp
+  git -C tmp/ clone --depth=1 https://github.com/DerekStride/tree-sitter-sql.git
+fi
+
+cd tmp/tree-sitter-sql
+
+npm install
+gcc -shared -o target/parser.so -fPIC src/parser.c -I./src
+
+cd ../..
+cp tmp/tree-sitter-sql/target/parser.so parsers/sql.so

data/deploy/install-treesitter

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+
+set -ex
+
+PREFIX="$(pwd)/tmp"
+
+mkdir -p tmp/lib tmp/lib
+cd tmp
+
+git clone --depth=1 https://github.com/tree-sitter/tree-sitter.git 2> /dev/null
+cd tree-sitter
+
+make
+PREFIX=$PREFIX make install
+cd ../..
+
+bundle config set build.tree_sitter \
+      --with-tree-sitter-dir=$PREFIX \
+      --with-tree-sitter-lib=$PREFIX/lib \
+      --with-tree-sitter-include=$PREFIX/include \
+      --with-opt-include=$PREFIX/include \
+      --with-opt-lib=$PREFIX/lib

data/lib/tree_stand/ast_modifier.rb

@@ -0,0 +1,25 @@
+module TreeStand
+  # An experimental class to modify the AST. I 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]
+    def initialize(tree)
+      @tree = tree
+    end
+
+    # @param query [String]
+    # @yieldparam self [self]
+    # @yieldparam match [TreeStand::Match]
+    # @return [void]
+    def on_match(query)
+      matches = @tree.query(query)
+
+      while !matches.empty?
+        yield self, matches.first
+        matches = @tree.query(query)
+      end
+    end
+  end
+end

data/lib/tree_stand/capture.rb

@@ -0,0 +1,45 @@
+module TreeStand
+  # Wrapper around a TreeSitter capture.
+  # @see TreeStand::Tree#query
+  # @see TreeStand::Match
+  class Capture
+    # @return [TreeStand::Match]
+    attr_reader :match
+    # @return [TreeSitter::Capture]
+    attr_reader :ts_capture
+
+    # @api private
+    def initialize(match, ts_capture)
+      @match = match
+      @ts_capture = ts_capture
+    end
+
+    # The name of the capture. TreeSitter strips the `@` from the capture name.
+    # @example
+    #   match = @tree.query(<<~QUERY).first
+    #     (identifier) @identifier.name
+    #   QUERY
+    #
+    #   capture = match.captures.first
+    #
+    #   assert_equal("identifier.name", capture.name)
+    # @return [String]
+    def name
+      @match.ts_query.capture_name_for_id(@ts_capture.index)
+    end
+
+    # @return [TreeStand::Node]
+    def node
+      TreeStand::Node.new(@match.tree, @ts_capture.node)
+    end
+
+    # @param other [Object]
+    # @return [bool]
+    def ==(other)
+      return false unless other.is_a?(TreeStand::Capture)
+
+      name == other.name &&
+        node == other.node
+    end
+  end
+end

data/lib/tree_stand/config.rb

@@ -0,0 +1,8 @@
+module TreeStand
+  # Global configuration for the gem.
+  # @api private
+  class Config
+    # @return [String]
+    attr_accessor :parser_path
+  end
+end

data/lib/tree_stand/match.rb

@@ -0,0 +1,57 @@
+module TreeStand
+  # Wrapper around a TreeSitter match.
+  # @see TreeStand::Tree#query
+  # @see TreeStand::Capture
+  class Match
+    # @return [TreeStand::Tree]
+    attr_reader :tree
+    # @return [TreeSitter::Query]
+    attr_reader :ts_query
+    # @return [TreeSitter::Match]
+    attr_reader :ts_match
+
+    # @api private
+    def initialize(tree, ts_query, ts_match)
+      @tree = tree
+      @ts_query = ts_query
+      @ts_match = ts_match
+
+      # TODO: This is a hack to get the captures to be populated.
+      # See: https://github.com/Faveod/ruby-tree-sitter/pull/16
+      captures
+    end
+
+    # Looks up a capture by name. TreeSitter strips the `@` from the capture name.
+    # @example
+    #   match = @tree.query(<<~QUERY).first
+    #     (identifier) @identifier.name
+    #   QUERY
+    #
+    #   refute_nil(match["identifier.name"])
+    # @param capture_name [String] The name of the capture from the query.
+    # @return [TreeStand::Capture, nil]
+    def [](capture_name)
+      captures.find { |capture| capture.name == capture_name }
+    end
+
+    # @return [Array<TreeStand::Capture>]
+    def captures
+      @captures ||= @ts_match.captures.map do |capture|
+        TreeStand::Capture.new(self, capture)
+      end
+    end
+
+    # @param other [Object]
+    # @return [bool]
+    def ==(other)
+      return false unless other.is_a?(TreeStand::Match)
+
+      captures == other.captures
+    end
+
+    # @return [TreeStand::Capture, nil]
+    def dig(name, *)
+      self[name]
+    end
+  end
+end

data/lib/tree_stand/node.rb

@@ -0,0 +1,76 @@
+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 Forwardable
+    include Enumerable
+
+    def_delegators :@ts_node, :type, :start_byte, :end_byte, :start_point, :end_point
+
+    # @api private
+    def initialize(tree, ts_node)
+      @tree = tree
+      @ts_node = ts_node
+      @fields = @ts_node.each_field.to_a.map(&:first)
+    end
+
+    # @return [TreeStand::Range]
+    def range
+      TreeStand::Range.new(
+        start_byte: @ts_node.start_byte,
+        end_byte: @ts_node.end_byte,
+        start_point: @ts_node.start_point,
+        end_point: @ts_node.end_point,
+      )
+    end
+
+    # Node includes enumerable so that you can iterate over the child nodes.
+    # @yieldparam child [TreeStand::Node]
+    # @return [Enumerator]
+    def each
+      @ts_node.each do |child|
+        yield TreeStand::Node.new(@tree, child)
+      end
+    end
+
+    # @return [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
+    # wraps the parent tree and has access to the source document.
+    # @return [String]
+    def text
+      @tree.document[@ts_node.start_byte...@ts_node.end_byte]
+    end
+
+    # This class overrides the `method_missing` method to delegate to the
+    # node's named children. This allows you to write code like this:
+    #   root = tree.root_node
+    #   child = root.expression
+    # @overload method_missing(field_name)
+    #   @param name [Symbol, String]
+    #   @return [TreeStand::Node] Child node for the given field name
+    #   @raise [NoMethodError] Raised if the node does not have child with name `field_name`
+    #
+    # @overload method_missing(method_name, *args, &block)
+    #   @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))
+    end
+
+    # @param other [Object]
+    # @return [bool]
+    def ==(other)
+      return false unless other.is_a?(TreeStand::Node)
+
+      range == other.range &&
+        type == other.type &&
+        text == other.text
+    end
+  end
+end

data/lib/tree_stand/parser.rb

@@ -0,0 +1,42 @@
+module TreeStand
+  # Wrapper around the TreeSitter parser. It looks up the parser by filename in
+  # the configured parsers directory.
+  # @example
+  #   TreeStand.configure do
+  #     config.parser_path = "path/to/parser/folder/"
+  #   end
+  #
+  #   # Looks for a parser in `path/to/parser/folder/sql.{so,dylib}`
+  #   sql_parser = TreeStand::Parser.new("sql")
+  #
+  #   # Looks for a parser in `path/to/parser/folder/ruby.{so,dylib}`
+  #   ruby_parser = TreeStand::Parser.new("ruby")
+  class Parser
+    # @return [TreeSitter::Language]
+    attr_reader :ts_language
+    # @return [TreeSitter::Parser]
+    attr_reader :ts_parser
+
+    # @param language [String]
+    def initialize(language)
+      @language_string = language
+      @ts_language = TreeSitter::Language.load(
+        language,
+        "#{TreeStand.config.parser_path}/#{language}.so"
+      )
+      @ts_parser = TreeSitter::Parser.new.tap do |parser|
+        parser.language = @ts_language
+      end
+    end
+
+    # Parse the provided document with the TreeSitter parser.
+    # @param tree [TreeStand::Tree]
+    # @param document [String]
+    # @return [TreeStand::Tree]
+    def parse_string(tree, document)
+      # There's a bug with passing a non-nil tree
+      ts_tree = @ts_parser.parse_string(nil, document)
+      TreeStand::Tree.new(self, ts_tree, document)
+    end
+  end
+end

data/lib/tree_stand/range.rb

@@ -0,0 +1,40 @@
+module TreeStand
+  # Wrapper around a TreeSitter range. This is mainly used to compare ranges.
+  class Range
+    # Point is a Struct containing the row and column from a TreeSitter point.
+    # TreeStand uses this to compare points.
+    # @!attribute [rw] row
+    #   @return [Integer]
+    # @!attribute [rw] column
+    #   @return [Integer]
+    Point = Struct.new(:row, :column)
+
+    # @return [Integer]
+    attr_reader :start_byte
+    # @return [Integer]
+    attr_reader :end_byte
+    # @return [TreeStand::Range::Point]
+    attr_reader  :start_point
+    # @return [TreeStand::Range::Point]
+    attr_reader  :end_point
+
+    # @api private
+    def initialize(start_byte:, end_byte:, start_point:, end_point:)
+      @start_byte = start_byte
+      @end_byte = end_byte
+      @start_point = Point.new(start_point.row, start_point.column)
+      @end_point = Point.new(end_point.row, end_point.column)
+    end
+
+    # @param other [Object]
+    # @return [bool]
+    def ==(other)
+      return false unless other.is_a?(TreeStand::Range)
+
+      @start_byte == other.start_byte &&
+        @end_byte == other.end_byte &&
+        @start_point == other.start_point &&
+        @end_point == other.end_point
+    end
+  end
+end

data/lib/tree_stand/tree.rb

@@ -0,0 +1,95 @@
+module TreeStand
+  # Wrapper around a TreeSitter tree.
+  #
+  # This class exposes a convient API for working with the tree. There are
+  # dangers in using this class. The tree is mutable and the document can be
+  # changed. This class does not protect against that.
+  #
+  # Some of the moetods on this class edit and re-parse the document updating
+  # the tree. Because the document is re-parsed, the tree will be different. Which
+  # means all outstanding nodes & ranges will be invalid.
+  #
+  # Methods that edit the document are suffixed with `!`, e.g. `#edit!`.
+  #
+  # It's often the case that you will want perfrom multiple edits. One such
+  # pattern is to call #query & #edit on all matches in a loop. It's important
+  # to keep the destructive nature of #edit in mind and re-issue the query
+  # after each edit.
+  #
+  # Another thing to keep in mind is that edits done later in the document will
+  # likely not affect the ranges that occur earlier in the document. This can
+  # be a convient property that could allow you to apply edits in a reverse order.
+  # 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
+    # @return [String]
+    attr_reader :document
+    # @return [TreeSitter::Tree]
+    attr_reader :ts_tree
+
+    # @api private
+    def initialize(parser, tree, document)
+      @parser = parser
+      @ts_tree = tree
+      @document = document
+    end
+
+    # @return [TreeStand::Node]
+    def root_node
+      TreeStand::Node.new(self, @ts_tree.root_node)
+    end
+
+    # TreeSitter uses a `TreeSitter::Cursor` to iterate over matches by calling
+    # `curser#next_match` repeatedly until it returns `nil`.
+    #
+    # This method does all of that for you and collects them into an array.
+    #
+    # @see TreeStand::Match
+    # @see TreeStand::Capture
+    #
+    # @param query_string [String]
+    # @return [Array<TreeStand::Match>]
+    def query(query_string)
+      ts_query = TreeSitter::Query.new(@parser.ts_language, query_string)
+      ts_cursor = TreeSitter::QueryCursor.exec(ts_query, @ts_tree.root_node)
+      matches = []
+      while match = ts_cursor.next_match
+        matches << TreeStand::Match.new(self, ts_query, match)
+      end
+      matches
+    end
+
+    # 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]
+    def edit!(range, replacement)
+      new_document = +""
+      new_document << @document[0...range.start_byte]
+      new_document << replacement
+      new_document << @document[range.end_byte..-1]
+      replace_with_new_doc(new_document)
+    end
+
+    # 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]
+    def delete!(range)
+      new_document = +""
+      new_document << @document[0...range.start_byte]
+      new_document << @document[range.end_byte..-1]
+      replace_with_new_doc(new_document)
+    end
+
+    private
+
+    def replace_with_new_doc(new_document)
+      @document = new_document
+      new_tree = @parser.parse_string(@ts_tree, @document)
+      @ts_tree = new_tree.ts_tree
+    end
+  end
+end

data/lib/tree_stand/version.rb

@@ -0,0 +1,4 @@
+module TreeStand
+  # The current version of the gem.
+  VERSION = "0.1.0"
+end

data/lib/tree_stand/visitor.rb

@@ -0,0 +1,59 @@
+module TreeStand
+  # Depth-first traversal through the tree, calling hooks at each stop.
+  #
+  # Hooks are language depended so are defined by creating methods on the
+  # visitor with the form `on_#{node.type}`.
+  #
+  # You can also define an `_on_default` method to run on all nodes.
+  #
+  # @example Create a visitor counting certain nodes
+  #   class CountingVisitor < TreeStand::Visitor
+  #     attr_reader :count
+  #
+  #     def initialize(document, type:)
+  #       super(document)
+  #       @type = type
+  #       @count = 0
+  #     end
+  #
+  #     def on_predicate(node)
+  #       # if this node matches our search, increment the counter
+  #       @count += 1 if node.type == @type
+  #     end
+  #   end
+  #
+  #   # Initialize a visitor
+  #   visitor = CountingVisitor.new(document, :predicate).visit
+  #   # Check the result
+  #   visitor.count
+  #   # => 3
+  class Visitor
+    # @param node [TreeStand::Node]
+    def initialize(node)
+      @node = node
+    end
+
+    # Run the visitor on the document and return self. Allows chaining create and visit.
+    # @example
+    #   visitor = CountingVisitor.new(node, :predicate).visit
+    # @return [self]
+    def visit
+      visit_node(@node)
+      self
+    end
+
+    private
+
+    def visit_node(node)
+      if respond_to?("on_#{node.type}")
+        public_send("on_#{node.type}", node)
+      elsif respond_to?(:_on_default)
+        _on_default(node)
+      end
+
+      node.each do |child|
+        visit_node(child)
+      end
+    end
+  end
+end

data/lib/tree_stand.rb

@@ -0,0 +1,33 @@
+require "tree_sitter"
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+# TreeStand is a high-level Ruby wrapper for {https://tree-sitter.github.io/tree-sitter tree-sitter} bindings. It makes
+# it easier to configure the parsers, and work with the underlying syntax tree.
+module TreeStand
+  # Common Ancestor for all TreeStand errors.
+  class Error < StandardError; end
+
+  class << self
+    # Easy configuration of the gem.
+    #
+    # @example
+    #   TreeStand.configure do
+    #     config.parser_path = "path/to/parser/folder/"
+    #   end
+    #
+    #   sql_parser = TreeStand::Parser.new("sql")
+    #   ruby_parser = TreeStand::Parser.new("ruby")
+    # @return [void]
+    def configure(&block)
+      instance_eval(&block)
+    end
+
+    # @return [TreeStand::Config]
+    def config
+      @config ||= Config.new
+    end
+  end
+end

data/service.yml

@@ -0,0 +1 @@
+classification: library

data/shipit.production.yml

@@ -0,0 +1,3 @@
+dependencies:
+  pre:
+    - ./deploy/install-treesitter

data/tree_stand.gemspec

@@ -0,0 +1,36 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "tree_stand/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "tree_stand"
+  spec.version       = TreeStand::VERSION
+  spec.authors       = ["derekstride"]
+  spec.email         = ["derek@stride.host", "opensource@shopify.com"]
+
+  spec.summary       = "A high-level Ruby wrapper for the Tree-sitter bindings"
+  spec.homepage      = "https://github.com/Shopify/tree_stand"
+  spec.license       = "MIT"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "zeitwerk"
+
+  spec.add_development_dependency "bundler", "~> 2.3"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest"
+  spec.add_development_dependency "pry-byebug"
+end

metadata

@@ -0,0 +1,146 @@
+--- !ruby/object:Gem::Specification
+name: tree_stand
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- derekstride
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2022-12-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- derek@stride.host
+- opensource@shopify.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".github/workflows/cla.yml"
+- ".gitignore"
+- ".shopify-build/VERSION"
+- ".shopify-build/tree-stand-publish-package.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- deploy/install-treesitter
+- lib/tree_stand.rb
+- lib/tree_stand/ast_modifier.rb
+- lib/tree_stand/capture.rb
+- lib/tree_stand/config.rb
+- lib/tree_stand/match.rb
+- lib/tree_stand/node.rb
+- lib/tree_stand/parser.rb
+- lib/tree_stand/range.rb
+- lib/tree_stand/tree.rb
+- lib/tree_stand/version.rb
+- lib/tree_stand/visitor.rb
+- parsers/.gitkeep
+- service.yml
+- shipit.production.yml
+- tree_stand.gemspec
+homepage: https://github.com/Shopify/tree_stand
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/Shopify/tree_stand
+  source_code_uri: https://github.com/Shopify/tree_stand
+  changelog_uri: https://github.com/Shopify/tree_stand
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key: 
+specification_version: 4
+summary: A high-level Ruby wrapper for the Tree-sitter bindings
+test_files: []