tree_haver 1.0.0

data/sig/tree_haver/backends.rbs

@@ -0,0 +1,285 @@
+# Type definitions for TreeHaver backends
+
+module TreeHaver
+  module Backends
+    # MRI backend using ruby_tree_sitter
+    module MRI
+      # Check if the MRI backend is available
+      def self.available?: () -> bool
+
+      # Get capabilities supported by this backend
+      def self.capabilities: () -> Hash[Symbol, untyped]
+
+      class Language
+        # Load a language from a shared library path
+        def self.from_path: (String path) -> untyped
+      end
+
+      class Parser
+        # Create a new parser instance
+        def initialize: () -> void
+
+        # Set the language for this parser
+        def language=: (untyped lang) -> untyped
+
+        # Parse source code
+        def parse: (String source) -> untyped
+
+        # Parse source code with optional incremental parsing
+        def parse_string: (untyped? old_tree, String source) -> untyped
+
+        private
+
+        @parser: untyped
+      end
+
+      class Tree
+      end
+
+      class Node
+      end
+    end
+
+    # FFI-based backend for calling libtree-sitter directly
+    module FFI
+      # Native FFI bindings to libtree-sitter
+      module Native
+        # Get list of candidate library names
+        def self.lib_candidates: () -> Array[String]
+
+        # Load the Tree-sitter runtime library
+        def self.try_load!: () -> void
+
+        # Check if the library is loaded
+        def self.loaded?: () -> bool
+
+        # FFI struct representation of TSNode
+        class TSNode < ::FFI::Struct
+        end
+
+        def self.ts_parser_new: () -> ::FFI::Pointer
+
+        def self.ts_parser_delete: (::FFI::Pointer ptr) -> void
+
+        def self.ts_parser_set_language: (::FFI::Pointer parser, ::FFI::Pointer language) -> bool
+
+        def self.ts_parser_parse_string: (::FFI::Pointer parser, ::FFI::Pointer old_tree, String source, Integer length) -> ::FFI::Pointer
+
+        def self.ts_tree_delete: (::FFI::Pointer ptr) -> void
+
+        def self.ts_tree_root_node: (::FFI::Pointer tree) -> TSNode
+
+        def self.ts_node_type: (TSNode node) -> String
+
+        def self.ts_node_child_count: (TSNode node) -> Integer
+
+        def self.ts_node_child: (TSNode node, Integer index) -> TSNode
+      end
+
+      # Check if the FFI backend is available
+      def self.available?: () -> bool
+
+      # Get capabilities supported by this backend
+      def self.capabilities: () -> Hash[Symbol, untyped]
+
+      class Language
+        # The FFI pointer to the TSLanguage struct
+        attr_reader pointer: ::FFI::Pointer
+
+        # Load a language from a shared library
+        def self.from_library: (String path, ?symbol: String?, ?name: String?) -> Language
+
+        # Alias for from_library
+        def self.from_path: (String path, ?symbol: String?, ?name: String?) -> Language
+
+        # Convert to FFI pointer
+        def to_ptr: () -> ::FFI::Pointer
+
+        private
+
+        def initialize: (::FFI::Pointer ptr) -> void
+      end
+
+      class Parser
+        # Create a new parser instance
+        def initialize: () -> void
+
+        # Get finalizer for cleanup
+        def self.finalizer: (::FFI::Pointer ptr) -> Proc
+
+        # Set the language for this parser
+        def language=: (Language lang) -> Language
+
+        # Parse source code into a syntax tree
+        def parse: (String source) -> Tree
+
+        private
+
+        @parser: ::FFI::Pointer
+      end
+
+      class Tree
+        # Get finalizer for cleanup
+        def self.finalizer: (::FFI::Pointer ptr) -> Proc
+
+        # Get the root node of the syntax tree
+        def root_node: () -> Node
+
+        private
+
+        def initialize: (::FFI::Pointer ptr) -> void
+
+        @ptr: ::FFI::Pointer
+      end
+
+      class Node
+        # Get the type name of this node
+        def type: () -> String
+
+        # Iterate over child nodes
+        def each: () { (Node child) -> void } -> nil
+                | () -> Enumerator[Node, nil]
+
+        private
+
+        def initialize: (Native::TSNode ts_node_value) -> void
+
+        @val: Native::TSNode
+      end
+    end
+
+    # Java backend for JRuby using java-tree-sitter
+    module Java
+      JAVA_PACKAGE: String
+
+      # Attempt to append JARs from ENV to JRuby classpath
+      def self.add_jars_from_env!: () -> void
+
+      # Check if the Java backend is available
+      def self.available?: () -> bool
+
+      # Reset the load state (for testing)
+      def self.reset!: () -> void
+
+      # Get the loaded Java classes
+      def self.java_classes: () -> Hash[Symbol, untyped]
+
+      # Get capabilities supported by this backend
+      def self.capabilities: () -> Hash[Symbol, untyped]
+
+      class Language
+        attr_reader impl: untyped
+
+        def initialize: (untyped impl) -> void
+
+        def self.from_library: (String path, ?symbol: String?, ?name: String?) -> Language
+
+        def self.from_path: (String path, ?symbol: String?, ?name: String?) -> Language
+      end
+
+      class Parser
+        def initialize: () -> void
+
+        def language=: (Language | untyped lang) -> void
+
+        def parse: (String source) -> Tree
+
+        def parse_string: (Tree? old_tree, String source) -> Tree
+
+        private
+
+        @parser: untyped
+      end
+
+      class Tree
+        attr_reader impl: untyped
+
+        def initialize: (untyped impl) -> void
+
+        def root_node: () -> Node
+
+        def edit: (
+          start_byte: Integer,
+          old_end_byte: Integer,
+          new_end_byte: Integer,
+          start_point: Hash[Symbol, Integer],
+          old_end_point: Hash[Symbol, Integer],
+          new_end_point: Hash[Symbol, Integer]
+        ) -> void
+      end
+
+      class Node
+        attr_reader impl: untyped
+
+        def initialize: (untyped impl) -> void
+
+        def type: () -> String
+
+        def child_count: () -> Integer
+
+        def child: (Integer index) -> Node
+
+        def each: () { (Node) -> void } -> void
+                | () -> Enumerator[Node, nil]
+
+        def start_byte: () -> Integer
+
+        def end_byte: () -> Integer
+
+        def start_point: () -> Hash[Symbol, Integer]
+
+        def end_point: () -> Hash[Symbol, Integer]
+
+        def has_error?: () -> bool
+
+        def missing?: () -> bool
+
+        def text: () -> String
+      end
+    end
+
+    # Rust backend using tree_stump
+    module Rust
+      # Check if the Rust backend is available
+      def self.available?: () -> bool
+
+      # Reset the load state (for testing)
+      def self.reset!: () -> void
+
+      # Get capabilities supported by this backend
+      def self.capabilities: () -> Hash[Symbol, untyped]
+
+      class Language
+        # Load a language from a shared library path
+        def self.from_library: (String path, ?symbol: String?, ?name: String?) -> untyped
+
+        # Alias for from_library
+        def self.from_path: (String path) -> untyped
+      end
+
+      class Parser
+        # Create a new parser instance
+        def initialize: () -> void
+
+        # Set the language for this parser
+        def language=: (untyped lang) -> untyped
+
+        # Parse source code
+        def parse: (String source) -> untyped
+
+        # Parse source code with optional incremental parsing
+        def parse_string: (untyped? old_tree, String source) -> untyped
+
+        private
+
+        @parser: untyped
+      end
+
+      class Tree
+      end
+
+      class Node
+      end
+    end
+  end
+end

data/sig/tree_haver/grammar_finder.rbs

@@ -0,0 +1,29 @@
+# Type signatures for TreeHaver::GrammarFinder
+module TreeHaver
+  # Generic utility for finding tree-sitter grammar shared libraries
+  class GrammarFinder
+    BASE_SEARCH_DIRS: Array[String]
+
+    attr_reader language_name: Symbol
+    attr_reader extra_paths: Array[String]
+
+    def initialize: (Symbol | String language_name, ?extra_paths: Array[String], ?validate: bool) -> void
+
+    def env_var_name: () -> String
+    def symbol_name: () -> String
+    def library_filename: () -> String
+    def search_paths: () -> Array[String]
+    def find_library_path: () -> String?
+    def find_library_path_safe: () -> String?
+    def available?: () -> bool
+    def available_safe?: () -> bool
+    def register!: (?raise_on_missing: bool) -> bool
+    def search_info: () -> Hash[Symbol, untyped]
+    def not_found_message: () -> String
+
+    private
+
+    def platform_extension: () -> String
+  end
+end
+

data/sig/tree_haver/path_validator.rbs

@@ -0,0 +1,31 @@
+# Type signatures for TreeHaver::PathValidator
+module TreeHaver
+  # Security utilities for validating paths before loading shared libraries
+  module PathValidator
+    ALLOWED_EXTENSIONS: Array[String]
+    DEFAULT_TRUSTED_DIRECTORIES: Array[String]
+    TRUSTED_DIRS_ENV_VAR: String
+    MAX_PATH_LENGTH: Integer
+    VALID_FILENAME_PATTERN: Regexp
+    VALID_LANGUAGE_PATTERN: Regexp
+    VALID_SYMBOL_PATTERN: Regexp
+
+    # Trusted directory management
+    def self.trusted_directories: () -> Array[String]
+    def self.add_trusted_directory: (String directory) -> void
+    def self.remove_trusted_directory: (String directory) -> void
+    def self.clear_custom_trusted_directories!: () -> void
+    def self.custom_trusted_directories: () -> Array[String]
+
+    # Validation methods
+    def self.safe_library_path?: (String? path, ?require_trusted_dir: bool) -> bool
+    def self.in_trusted_directory?: (String? path) -> bool
+    def self.safe_language_name?: (String | Symbol | nil name) -> bool
+    def self.safe_symbol_name?: (String? symbol) -> bool
+    def self.safe_backend_name?: (String | Symbol | nil backend) -> bool
+    def self.sanitize_language_name: (String | Symbol | nil name) -> Symbol?
+    def self.validation_errors: (String? path) -> Array[String]
+    def self.windows_absolute_path?: (String path) -> bool
+  end
+end
+

data/sig/tree_haver.rbs

@@ -0,0 +1,131 @@
+# Type definitions for TreeHaver
+#
+# TreeHaver is a cross-Ruby adapter for the Tree-sitter parsing library
+
+module TreeHaver
+  VERSION: String
+
+  # Base error class
+  class Error < StandardError
+  end
+
+  # Raised when a backend or feature is not available
+  class NotAvailable < Error
+  end
+
+  # Module namespace for backend implementations
+  module Backends
+  end
+
+  # Get the current backend selection
+  def self.backend: () -> Symbol
+
+  # Set the backend to use
+  def self.backend=: (Symbol | String | nil name) -> (Symbol | nil)
+
+  # Reset backend selection memoization
+  def self.reset_backend!: (?to: Symbol | String | nil) -> void
+
+  # Determine the concrete backend module to use
+  def self.backend_module: () -> Module?
+
+  # Get capabilities of the current backend
+  def self.capabilities: () -> Hash[Symbol, untyped]
+
+  # Register a language helper by name
+  def self.register_language: (Symbol | String name, path: String, ?symbol: String?) -> void
+
+  # Unregister a previously registered language helper
+  def self.unregister_language: (Symbol | String name) -> void
+
+  # Clear all registered languages
+  def self.clear_languages!: () -> void
+
+  # Fetch a registered language entry
+  def self.registered_language: (Symbol | String name) -> Hash[Symbol, String?]?
+
+  # Represents a Tree-sitter language grammar
+  class Language
+    # Load a language grammar from a shared library
+    def self.from_library: (String path, ?symbol: String?, ?name: String?) -> Language
+
+    # Alias for from_library
+    def self.from_path: (String path, ?symbol: String?, ?name: String?) -> Language
+
+    def self.method_missing: (Symbol method_name, *untyped args, **untyped kwargs) ?{ () -> untyped } -> Language
+
+    def self.respond_to_missing?: (Symbol method_name, ?bool include_private) -> bool
+  end
+
+  # Represents a Tree-sitter parser instance
+  class Parser
+    # Create a new parser instance
+    def initialize: () -> void
+
+    # Set the language grammar for this parser
+    def language=: (Language lang) -> Language
+
+    # Parse source code into a syntax tree
+    def parse: (String source) -> Tree
+
+    private
+
+    @impl: untyped
+  end
+
+  # Represents a parsed syntax tree
+  class Tree
+    # Get the root node of the syntax tree
+    def root_node: () -> Node
+
+    private
+
+    def initialize: (untyped impl) -> void
+
+    @impl: untyped
+  end
+
+  # Represents a node in the syntax tree
+  class Node
+    # Get the type name of this node
+    def type: () -> String
+
+    # Iterate over child nodes
+    def each: () { (Node child) -> void } -> nil
+            | () -> Enumerator[Node, nil]
+
+    private
+
+    def initialize: (untyped impl) -> void
+
+    @impl: untyped
+  end
+
+  # Thread-safe language registrations and cache
+  module LanguageRegistry
+    # Register a language helper by name
+    def self.register: (Symbol | String name, path: String, ?symbol: String?) -> void
+
+    # Unregister a previously registered language helper
+    def self.unregister: (Symbol | String name) -> void
+
+    # Fetch a registration entry
+    def self.registered: (Symbol | String name) -> Hash[Symbol, String?]?
+
+    # Clear all registrations
+    def self.clear_registrations!: () -> void
+
+    # Fetch a cached language by key or compute and store it
+    def self.fetch: [T] (Array[untyped] key) { () -> T } -> T
+
+    # Clear the language cache
+    def self.clear_cache!: () -> void
+
+    # Clear everything (registrations and cache)
+    def self.clear_all!: () -> void
+  end
+
+  module Version
+    VERSION: String
+  end
+end