tree_haver 5.0.5 → 7.0.0

data/RUBOCOP.md

@@ -1,71 +0,0 @@
-# RuboCop Usage Guide
-
-## Overview
-
-A tale of two RuboCop plugin gems.
-
-### RuboCop Gradual
-
-This project uses `rubocop_gradual` instead of vanilla RuboCop for code style checking. The `rubocop_gradual` tool allows for gradual adoption of RuboCop rules by tracking violations in a lock file.
-
-### RuboCop LTS
-
-This project uses `rubocop-lts` to ensure, on a best-effort basis, compatibility with Ruby >= 1.9.2.
-RuboCop rules are meticulously configured by the `rubocop-lts` family of gems to ensure that a project is compatible with a specific version of Ruby. See: https://rubocop-lts.gitlab.io for more.
-
-## Checking RuboCop Violations
-
-To check for RuboCop violations in this project, always use:
-
-```bash
-bundle exec rake rubocop_gradual:check
-```
-
-**Do not use** the standard RuboCop commands like:
-- `bundle exec rubocop`
-- `rubocop`
-
-## Understanding the Lock File
-
-The `.rubocop_gradual.lock` file tracks all current RuboCop violations in the project. This allows the team to:
-
-1. Prevent new violations while gradually fixing existing ones
-2. Track progress on code style improvements
-3. Ensure CI builds don't fail due to pre-existing violations
-
-## Common Commands
-
-- **Check violations**
-    - `bundle exec rake rubocop_gradual`
-    - `bundle exec rake rubocop_gradual:check`
-- **(Safe) Autocorrect violations, and update lockfile if no new violations**
-  - `bundle exec rake rubocop_gradual:autocorrect`
-- **Force update the lock file (w/o autocorrect) to match violations present in code**
-  - `bundle exec rake rubocop_gradual:force_update`
-
-## Workflow
-
-1. Before submitting a PR, run `bundle exec rake rubocop_gradual:autocorrect`
-   a. or just the default `bundle exec rake`, as autocorrection is a pre-requisite of the default task.
-2. If there are new violations, either:
-   - Fix them in your code
-   - Run `bundle exec rake rubocop_gradual:force_update` to update the lock file (only for violations you can't fix immediately)
-3. Commit the updated `.rubocop_gradual.lock` file along with your changes
-
-## Never add inline RuboCop disables
-
-Do not add inline `rubocop:disable` / `rubocop:enable` comments anywhere in the codebase (including specs, except when following the few existing `rubocop:disable` patterns for a rule already being disabled elsewhere in the code). We handle exceptions in two supported ways:
-
-- Permanent/structural exceptions: prefer adjusting the RuboCop configuration (e.g., in `.rubocop.yml`) to exclude a rule for a path or file pattern when it makes sense project-wide.
-- Temporary exceptions while improving code: record the current violations in `.rubocop_gradual.lock` via the gradual workflow:
-  - `bundle exec rake rubocop_gradual:autocorrect` (preferred; will autocorrect what it can and update the lock only if no new violations were introduced)
-  - If needed, `bundle exec rake rubocop_gradual:force_update` (as a last resort when you cannot fix the newly reported violations immediately)
-
-In general, treat the rules as guidance to follow; fix violations rather than ignore them. For example, RSpec conventions in this project expect `described_class` to be used in specs that target a specific class under test.
-
-## Benefits of rubocop_gradual
-
-- Allows incremental adoption of code style rules
-- Prevents CI failures due to pre-existing violations
-- Provides a clear record of code style debt
-- Enables focused efforts on improving code quality over time

data/SECURITY.md

@@ -1,21 +0,0 @@
-# Security Policy
-
-## Supported Versions
-
-| Version  | Supported |
-|----------|-----------|
-| 5.latest | ✅         |
-
-## Security contact information
-
-To report a security vulnerability, please use the
-[Tidelift security contact](https://tidelift.com/security).
-Tidelift will coordinate the fix and disclosure.
-
-## Additional Support
-
-If you are interested in support for versions older than the latest release,
-please consider sponsoring the project / maintainer @ https://liberapay.com/pboling/donate,
-or find other sponsorship links in the [README].
-
-[README]: README.md

data/lib/tree_haver/backend_api.rb

@@ -1,349 +0,0 @@
-# frozen_string_literal: true
-
-module TreeHaver
-  # Backend API contract definitions and validation
-  #
-  # This module defines the expected API surface for TreeHaver backends.
-  # Each backend must provide Parser, Language, Tree, and Node classes/objects
-  # that conform to these interfaces.
-  #
-  # == Architecture
-  #
-  # TreeHaver backends fall into two categories:
-  #
-  # 1. **Raw backends** (MRI, FFI, Rust) - Return raw tree-sitter objects
-  #    (e.g., ::TreeSitter::Node). TreeHaver::Node wraps these and provides
-  #    a unified API via method delegation.
-  #
-  # 2. **Wrapper backends** (Java, Citrus, Prism, Psych, Commonmarker, Markly) -
-  #    Return their own wrapper objects that must implement the expected API
-  #    directly, since TreeHaver::Node will delegate to them.
-  #
-  # == Usage
-  #
-  #   # Validate a backend's API compliance
-  #   TreeHaver::BackendAPI.validate!(backend_module)
-  #
-  #   # Check specific class compliance
-  #   TreeHaver::BackendAPI.validate_node!(node_instance)
-  #
-  module BackendAPI
-    # Required methods for Language class/instances
-    #
-    # All backends MUST implement `from_library` for API consistency.
-    # Language-specific backends (Psych, Prism, Commonmarker, Markly) should
-    # implement `from_library` to accept (and ignore) path/symbol parameters,
-    # returning their single supported language.
-    #
-    # This ensures `TreeHaver.parser_for(:yaml)` works regardless of backend -
-    # tree-sitter backends load the YAML grammar, while Psych returns its
-    # built-in YAML support.
-    #
-    # Convenience methods (yaml, ruby, markdown) are OPTIONAL and only make
-    # sense on backends that only support one language family.
-    LANGUAGE_CLASS_METHODS = %i[
-      from_library
-    ].freeze
-
-    # Optional convenience methods for language-specific backends
-    # These are NOT required - they're just shortcuts for single-language backends
-    LANGUAGE_OPTIONAL_CLASS_METHODS = %i[
-      yaml
-      ruby
-      markdown
-    ].freeze
-
-    LANGUAGE_INSTANCE_METHODS = %i[
-      backend
-    ].freeze
-
-    # Required methods for Parser class/instances
-    PARSER_CLASS_METHODS = %i[
-      new
-    ].freeze
-
-    PARSER_INSTANCE_METHODS = %i[
-      language=
-      parse
-    ].freeze
-
-    # Optional Parser methods (for incremental parsing)
-    PARSER_OPTIONAL_METHODS = %i[
-      parse_string
-    ].freeze
-
-    # Required methods for Tree instances
-    # Note: Tree is returned by Parser#parse, not instantiated directly
-    TREE_INSTANCE_METHODS = %i[
-      root_node
-    ].freeze
-
-    # Optional Tree methods (for incremental parsing)
-    TREE_OPTIONAL_METHODS = %i[
-      edit
-    ].freeze
-
-    # Required methods for Node instances returned by wrapper backends
-    # These are the methods TreeHaver::Node delegates to inner_node
-    #
-    # Raw backends (MRI, FFI, Rust) return tree-sitter native nodes which
-    # have their own API. TreeHaver::Node handles the translation.
-    #
-    # Wrapper backends (Java, Citrus, etc.) must implement these methods
-    # on their Node class since TreeHaver::Node delegates to them.
-    NODE_INSTANCE_METHODS = %i[
-      type
-      child_count
-      child
-      start_byte
-      end_byte
-    ].freeze
-
-    # Optional Node methods - should return nil if not supported
-    NODE_OPTIONAL_METHODS = %i[
-      parent
-      next_sibling
-      prev_sibling
-      named?
-      has_error?
-      missing?
-      text
-      child_by_field_name
-      start_point
-      end_point
-    ].freeze
-
-    # Methods that have common aliases across backends
-    NODE_ALIASES = {
-      type: %i[kind],
-      named?: %i[is_named? is_named],
-      has_error?: %i[has_error],
-      missing?: %i[is_missing? is_missing],
-      next_sibling: %i[next_named_sibling],
-      prev_sibling: %i[previous_sibling previous_named_sibling prev_named_sibling],
-    }.freeze
-
-    class << self
-      # Validate a backend module for API compliance
-      #
-      # @param backend_module [Module] The backend module (e.g., TreeHaver::Backends::Java)
-      # @param strict [Boolean] If true, raise on missing optional methods
-      # @return [Hash] Validation results with :valid, :errors, :warnings keys
-      def validate(backend_module, strict: false)
-        results = {
-          valid: true,
-          errors: [],
-          warnings: [],
-          capabilities: {},
-        }
-
-        # Check module-level methods
-        validate_module_methods(backend_module, results)
-
-        # Check Language class
-        if backend_module.const_defined?(:Language)
-          validate_language(backend_module::Language, results)
-        else
-          results[:errors] << "Missing Language class"
-          results[:valid] = false
-        end
-
-        # Check Parser class
-        if backend_module.const_defined?(:Parser)
-          validate_parser(backend_module::Parser, results)
-        else
-          results[:errors] << "Missing Parser class"
-          results[:valid] = false
-        end
-
-        # Check Tree class if present (some backends return raw trees)
-        if backend_module.const_defined?(:Tree)
-          validate_tree(backend_module::Tree, results)
-        else
-          results[:warnings] << "No Tree class (backend returns raw trees)"
-        end
-
-        # Check Node class if present (wrapper backends)
-        if backend_module.const_defined?(:Node)
-          validate_node_class(backend_module::Node, results, strict: strict)
-        else
-          results[:warnings] << "No Node class (backend returns raw nodes, TreeHaver::Node will wrap)"
-        end
-
-        # Fail on warnings in strict mode
-        if strict && results[:warnings].any?
-          results[:valid] = false
-        end
-
-        results
-      end
-
-      # Validate and raise on failure
-      #
-      # @param backend_module [Module] The backend module to validate
-      # @param strict [Boolean] If true, treat warnings as errors
-      # @raise [TreeHaver::Error] if validation fails
-      # @return [Hash] Validation results if valid
-      def validate!(backend_module, strict: false)
-        results = validate(backend_module, strict: strict)
-        unless results[:valid]
-          raise TreeHaver::Error,
-            "Backend #{backend_module.name} API validation failed:\n  " \
-              "Errors: #{results[:errors].join(", ")}\n  " \
-              "Warnings: #{results[:warnings].join(", ")}"
-        end
-        results
-      end
-
-      # Validate a Node instance for API compliance
-      #
-      # @param node [Object] A node instance to validate
-      # @return [Hash] Validation results
-      def validate_node_instance(node)
-        results = {
-          valid: true,
-          errors: [],
-          warnings: [],
-          supported_methods: [],
-          unsupported_methods: [],
-        }
-
-        # Check required methods
-        NODE_INSTANCE_METHODS.each do |method|
-          if responds_to_with_aliases?(node, method)
-            results[:supported_methods] << method
-          else
-            results[:errors] << "Missing required method: #{method}"
-            results[:valid] = false
-          end
-        end
-
-        # Check optional methods
-        NODE_OPTIONAL_METHODS.each do |method|
-          if responds_to_with_aliases?(node, method)
-            results[:supported_methods] << method
-          else
-            results[:unsupported_methods] << method
-            results[:warnings] << "Missing optional method: #{method}"
-          end
-        end
-
-        results
-      end
-
-      private
-
-      def validate_module_methods(mod, results)
-        unless mod.singleton_class.method_defined?(:available?)
-          results[:errors] << "Missing module method: available?"
-          results[:valid] = false
-        end
-
-        unless mod.singleton_class.method_defined?(:capabilities)
-          results[:warnings] << "Missing module method: capabilities"
-        end
-      end
-
-      def validate_language(klass, results)
-        # from_library is REQUIRED for all backends
-        # Language-specific backends should implement it to ignore path/symbol
-        # and return their single language (for API consistency)
-        unless klass.singleton_class.method_defined?(:from_library)
-          results[:errors] << "Language missing required class method: from_library"
-          results[:valid] = false
-        end
-
-        # Check for optional convenience methods
-        optional_methods = LANGUAGE_OPTIONAL_CLASS_METHODS.select { |m| klass.singleton_class.method_defined?(m) }
-        if optional_methods.any?
-          results[:capabilities][:language_shortcuts] = optional_methods
-        end
-
-        results[:capabilities][:language] = {
-          class_methods: LANGUAGE_CLASS_METHODS.select { |m| klass.singleton_class.method_defined?(m) } +
-            optional_methods,
-        }
-      end
-
-      def validate_parser(klass, results)
-        PARSER_CLASS_METHODS.each do |method|
-          unless klass.singleton_class.method_defined?(method)
-            results[:errors] << "Parser missing class method: #{method}"
-            results[:valid] = false
-          end
-        end
-
-        # Check instance methods by inspecting the class
-        PARSER_INSTANCE_METHODS.each do |method|
-          unless klass.method_defined?(method) || klass.private_method_defined?(method)
-            results[:errors] << "Parser missing instance method: #{method}"
-            results[:valid] = false
-          end
-        end
-
-        PARSER_OPTIONAL_METHODS.each do |method|
-          unless klass.method_defined?(method)
-            results[:warnings] << "Parser missing optional method: #{method}"
-          end
-        end
-      end
-
-      def validate_tree(klass, results)
-        TREE_INSTANCE_METHODS.each do |method|
-          unless klass.method_defined?(method)
-            results[:errors] << "Tree missing instance method: #{method}"
-            results[:valid] = false
-          end
-        end
-
-        TREE_OPTIONAL_METHODS.each do |method|
-          unless klass.method_defined?(method)
-            results[:warnings] << "Tree missing optional method: #{method}"
-          end
-        end
-      end
-
-      def validate_node_class(klass, results, strict: false)
-        NODE_INSTANCE_METHODS.each do |method|
-          unless has_method_or_alias?(klass, method)
-            results[:errors] << "Node missing required method: #{method}"
-            results[:valid] = false
-          end
-        end
-
-        NODE_OPTIONAL_METHODS.each do |method|
-          unless has_method_or_alias?(klass, method)
-            msg = "Node missing optional method: #{method}"
-            if strict
-              results[:errors] << msg
-              results[:valid] = false
-            else
-              results[:warnings] << msg
-            end
-          end
-        end
-
-        results[:capabilities][:node] = {
-          required: NODE_INSTANCE_METHODS.select { |m| has_method_or_alias?(klass, m) },
-          optional: NODE_OPTIONAL_METHODS.select { |m| has_method_or_alias?(klass, m) },
-        }
-      end
-
-      def has_method_or_alias?(klass, method)
-        return true if klass.method_defined?(method)
-
-        # Check aliases
-        aliases = NODE_ALIASES[method] || []
-        aliases.any? { |alt| klass.method_defined?(alt) }
-      end
-
-      def responds_to_with_aliases?(obj, method)
-        return true if obj.respond_to?(method)
-
-        # Check aliases
-        aliases = NODE_ALIASES[method] || []
-        aliases.any? { |alt| obj.respond_to?(alt) }
-      end
-    end
-  end
-end