tree_haver 4.0.5 → 5.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3f6764cb2c0399f4255cc4536745156cd8391fa1818b9b84db9d0b39ca17fa9
-  data.tar.gz: d9e12364a4480307b8cd8a7ca0315bbeba7764c6bfe20747b3b8ff792e9fe2e7
+  metadata.gz: bf24354cab86e375d66426a05aa6afa5d852bc1941a8fe1235f0647a89891e77
+  data.tar.gz: 25f91798a18044f1e0b1b5deb83cc61fe734bd05f7391225a36dd11dbb47a941
 SHA512:
-  metadata.gz: 6a95af29f397cea98bc29a93885f9285637ae82469417b62c981629d21861f5b64560ca0e2c21b0405abdc541d04b39f6c1848928273b82679ba3f169f885549
-  data.tar.gz: bbd048585aed007eed86bdd117b18cff1e72e378fd20bbc07a252b6095ab38d4c5c9eb83fc572c21bcd07e515b2ad1bfae50f9705b75f69f4d955ecf65d4b844
+  metadata.gz: dcd6d8d3e481bd1e5201a83441d63d41af9be368eb8c746e7d27a44dfa7cb76345a014f7a426557e40c1becfecf9f9e9f60176d8c6d53a57978077146137f13d
+  data.tar.gz: 5f1dc4d8844b5da005d5d1ef59ac3a74c1794ee95d25de1c5c67a13198f671a06ad45ce82d3530e875230374339c5a749f2a3e96ffe555b194a05b7a6cc4a4ef

data/CHANGELOG.md

@@ -1,4 +1,4 @@
-ed# Changelog
+# Changelog
 
 [![SemVer 2.0.0][📌semver-img]][📌semver] [![Keep-A-Changelog 1.0.0][📗keep-changelog-img]][📗keep-changelog]
 
@@ -30,6 +30,195 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [5.0.1] - 2026-01-11
+
+- TAG: [v5.0.1][5.0.1t]
+- COVERAGE: 90.79% -- 2308/2542 lines in 30 files
+- BRANCH COVERAGE: 78.09% -- 930/1191 branches in 30 files
+- 94.76% documented
+
+### Added
+
+- `TreeHaver::RSpec::TestableNode` - A testable node class for creating mock TreeHaver::Node instances
+  in tests without requiring an actual parser backend. Available via `require "tree_haver/rspec/testable_node"`
+  or automatically when using `require "tree_haver/rspec"`.
+  - `TestableNode.create(type:, text:, ...)` - Create a single test node
+  - `TestableNode.create_list(...)` - Create multiple test nodes
+  - `MockInnerNode` - The underlying mock that simulates backend-specific nodes
+  - Top-level `TestableNode` constant for convenience in specs
+- **Fully Dynamic Tag Registration** in `TreeHaver::BackendRegistry`:
+  - `register_tag(tag_name, category:, backend_name:, require_path:)` - Register a complete dependency tag
+    with lazy loading support. External gems can now get full RSpec tag support without any hardcoded
+    knowledge in tree_haver.
+  - `tag_available?(tag_name)` - Check if a tag's dependency is available, with automatic lazy loading
+    via the registered `require_path`
+  - `registered_tags` - Get all registered tag names
+  - `tags_by_category(category)` - Get tags filtered by category (:backend, :gem, :parsing, :grammar, :engine, :other)
+  - `tag_metadata(tag_name)` - Get full metadata for a registered tag
+  - `tag_summary` - Get availability status of all registered tags
+
+### Changed
+
+- **Fully Dynamic Backend Availability** in `BackendRegistry` and `DependencyTags`:
+  - `register_tag` now dynamically defines `*_available?` methods on `DependencyTags` at registration time
+  - External gems automatically get availability methods when they call `register_tag`
+  - No changes to tree_haver are needed for new external backend gems
+  - Built-in backends (prism, psych, citrus, parslet) retain explicit methods
+  - `summary` method dynamically includes registered backends from BackendRegistry
+  - `backend_availability_methods` and `backend_tags` hashes are built dynamically
+- RSpec exclusion filters for backend tags are configured dynamically from BackendRegistry
+
+### Fixed
+
+- **`TreeHaver::Parser#unwrap_language` bug fix for MRI and Rust backends**
+  - `:mri` and `:rust` cases were not returning the unwrapped language value
+  - The code called `lang.to_language` / `lang.inner_language` / `lang.name` but didn't `return` the result
+  - Now properly returns the unwrapped language for all backend types
+- `any_markdown_backend_available?` now uses `BackendRegistry.tag_available?` instead of calling
+  `markly_available?` and `commonmarker_available?` directly. This fixes `NoMethodError` when
+  the external markdown backend gems haven't registered their tags yet.
+
+## [5.0.0] - 2026-01-11
+
+- TAG: [v5.0.0][5.0.0t]
+- COVERAGE: 92.04% -- 2289/2487 lines in 30 files
+- BRANCH COVERAGE: 79.33% -- 929/1171 branches in 30 files
+- 96.21% documented
+
+### Added
+
+- **Shared Example Groups for Backend API Compliance Testing**
+  - `node_api_examples.rb` - Tests for Node API compliance:
+    - `"node api compliance"` - Core Node interface (type, start_byte, end_byte, children)
+    - `"node position api"` - Position API (start_point, end_point, start_line, end_line, source_position)
+    - `"node children api"` - Children traversal (#child, #first_child, #last_child)
+    - `"node enumerable behavior"` - Enumerable methods (#each, #map, #select, #find)
+    - `"node comparison behavior"` - Comparison and equality (#==, #<=>, #hash)
+    - `"node text extraction"` - Text content (#text, #to_s)
+    - `"node inspection"` - Debug output (#inspect)
+  - `tree_api_examples.rb` - Tests for Tree API compliance:
+    - `"tree api compliance"` - Core Tree interface (root_node, source, errors, warnings, comments)
+    - `"tree error handling"` - Error detection (#has_error?, #errors)
+    - `"tree traversal"` - Depth-first traversal via root_node
+  - `parser_api_examples.rb` - Tests for Parser API compliance:
+    - `"parser api compliance"` - Core Parser interface (#parse, #parse_string, #language=)
+    - `"parser incremental parsing"` - Incremental parsing support
+    - `"parser error handling"` - Error recovery behavior
+  - `language_api_examples.rb` - Tests for Language API compliance:
+    - `"language api compliance"` - Core Language interface (#backend, #name/#language_name)
+    - `"language comparison"` - Comparison and equality
+    - `"language factory methods"` - Factory methods (.from_library, .from_path)
+  - `backend_api_examples.rb` - Tests for Backend module API compliance:
+    - `"backend module api"` - Backend availability and capabilities
+    - `"backend class structure"` - Nested class verification
+    - `"backend integration"` - Full parse cycle testing
+  - `spec/support/shared_examples.rb` - Master loader for all shared examples
+  - `spec/integration/backend_api_compliance_spec.rb` - Integration tests using all shared examples
+- **Parslet Backend**: New pure Ruby PEG parser backend (`TreeHaver::Backends::Parslet`)
+  - Wraps Parslet-based parsers (like the `toml` gem) to provide a pure Ruby alternative to tree-sitter
+  - `Parslet.available?` - Check if parslet gem is available
+  - `Parslet.capabilities` - Returns `{ backend: :parslet, query: false, bytes_field: true, incremental: false, pure_ruby: true }`
+  - `Parslet::Language` - Wrapper for Parslet grammar classes
+    - `Language.new(grammar_class)` - Create from a Parslet::Parser subclass
+    - `Language.from_library(path, symbol:, name:)` - API-compatible lookup via LanguageRegistry
+    - `#language_name` / `#name` - Derive language name from grammar class
+  - `Parslet::Parser` - Wrapper that creates parser instances from grammar classes
+    - Accepts both raw grammar class and Language wrapper (normalized API)
+  - `Parslet::Tree` - Wraps Parslet parse results, inherits from `Base::Tree`
+  - `Parslet::Node` - Unified node interface, inherits from `Base::Node`
+    - Supports both Hash nodes (with named children) and Array nodes (with indexed children)
+    - `#type` - Returns the node type (key name or "array"/"document")
+    - `#children` - Returns child nodes
+    - `#child_by_field_name(name)` - Access named children in Hash nodes
+    - `#text` - Returns the matched text from Parslet::Slice
+    - `#start_byte`, `#end_byte` - Byte positions from Parslet::Slice
+    - `#start_point`, `#end_point` - Line/column positions (computed from source)
+  - Registered with `BackendRegistry.register_availability_checker(:parslet)`
+- **RSpec Dependency Tags**: Added `parslet_available?` method
+  - Checks if parslet gem is installed via `BackendRegistry.available?(:parslet)`
+  - `:parslet_backend` tag for specs requiring Parslet
+  - `:not_parslet_backend` negated tag for specs that should skip when Parslet is available
+- **RSpec Dependency Tags**: Added `toml_gem_available?` method and updated `any_toml_backend_available?`
+  - `:toml_gem` tag for specs requiring the `toml` gem to be available
+  - `:not_toml_gem` negated tag for specs that should skip when the `toml` gem is not available
+- **ParsletGrammarFinder**: Utility for discovering and registering Parslet grammar gems
+  - `ParsletGrammarFinder.new(language:, gem_name:, grammar_const:, require_path:)` - Find Parslet grammars
+  - `#available?` - Check if the Parslet grammar gem is installed and functional
+  - `#grammar_class` - Get the resolved Parslet::Parser subclass
+  - `#register!` - Register the grammar with TreeHaver
+  - Auto-loads via `TreeHaver::PARSLET_DEFAULTS` for known languages (toml)
+- **TreeHaver.register_language**: Extended with `grammar_class:` parameter for Parslet grammars
+- **TreeHaver.parser_for**: Extended with `parslet_config:` parameter for explicit Parslet configuration
+- `MRI::Language#language_name` / `#name` - Derive language name from symbol or path
+- `FFI::Language#language_name` / `#name` - Derive language name from symbol or path
+- **spec_helper.rb**: Added `require "toml"` to load the toml gem for Parslet backend tests
+
+### Changed
+
+- **BREAKING: `TreeHaver::Language` converted from class to module**
+  - Previously `TreeHaver::Language` was a class that wrapped backend language objects
+  - Now `TreeHaver::Language` is a module providing factory methods (`method_missing` for dynamic language loading)
+  - Backend-specific language classes (e.g., `TreeHaver::Backends::MRI::Language`) are now the concrete implementations
+  - Code that instantiated `TreeHaver::Language.new(...)` directly must be updated to use backend-specific classes or the factory methods
+- **BREAKING: `TreeHaver::Tree` now inherits from `TreeHaver::Base::Tree`**
+  - `TreeHaver::Tree` is now a proper subclass of `TreeHaver::Base::Tree`
+  - Inherits `inner_tree`, `source`, `lines` attributes from base class
+  - Base class provides default implementations; subclass documents divergence
+- **BREAKING: `TreeHaver::Node` now inherits from `TreeHaver::Base::Node`**
+  - `TreeHaver::Node` is now a proper subclass of `TreeHaver::Base::Node`
+  - Inherits `inner_node`, `source`, `lines` attributes from base class
+  - Base class documents the API contract; subclass documents divergence
+- **BREAKING: `Citrus::Node` and `Citrus::Tree` now inherit from Base classes**
+  - `Citrus::Node` now inherits from `TreeHaver::Base::Node`
+  - `Citrus::Tree` now inherits from `TreeHaver::Base::Tree`
+  - Removes duplicated methods, uses inherited implementations
+  - Adds `#language_name` / `#name` methods for API compliance
+- **BREAKING: `Parslet::Node` and `Parslet::Tree` now inherit from Base classes**
+  - `Parslet::Node` now inherits from `TreeHaver::Base::Node`
+  - `Parslet::Tree` now inherits from `TreeHaver::Base::Tree`
+  - Removes duplicated methods, uses inherited implementations
+- **Base::Node#child now returns nil for negative indices** (tree-sitter API compatibility)
+- **Citrus::Parser#language= now accepts Language wrapper or raw grammar module**
+  - Both patterns now work: `parser.language = TomlRB::Document` or `parser.language = Citrus::Language.new(TomlRB::Document)`
+- **Parslet::Parser#language= now accepts Language wrapper or raw grammar class**
+  - Both patterns now work: `parser.language = TOML::Parslet` or `parser.language = Parslet::Language.new(TOML::Parslet)`
+- **TreeHaver::Parser#unwrap_language** now passes Language wrappers directly to Citrus/Parslet backends
+  - Previously unwrapped to raw grammar; now backends handle their own Language wrappers
+- **Language.method_missing**: Now recognizes `:parslet` backend type and creates `Parslet::Language` instances
+- **Parser**: Updated to recognize Parslet languages and switch to Parslet parser automatically
+  - `#backend` now returns `:parslet` for Parslet-based parsers
+  - `#language=` detects `Parslet::Language` and switches implementation
+  - `handle_parser_creation_failure` tries Parslet as fallback after Citrus
+  - `unwrap_language` extracts `grammar_class` for Parslet languages
+
+### Fixed
+
+- **FFI Backend Compliance Tests**: Fixed tests to use `TreeHaver::Parser` wrapper instead of raw `FFI::Parser`
+  - Raw FFI classes (`FFI::Tree`, `FFI::Node`) don't have full API (missing `#children`, `#text`, `#source`, etc.)
+  - TreeHaver wrapper classes (`TreeHaver::Tree`, `TreeHaver::Node`) provide the complete unified API
+  - Tests now properly test the wrapped API that users actually interact with
+- **Parslet TOML Sources**: Fixed test sources to be valid for the `toml` gem's Parslet grammar
+  - Grammar requires table sections (not bare key-value pairs at root)
+  - Grammar requires trailing newlines
+- **Examples**: Fixed broken markdown examples that referenced non-existent TreeHaver backends
+  - `commonmarker_markdown.rb` - Rewrote to use commonmarker gem directly (not a TreeHaver backend)
+  - `markly_markdown.rb` - Rewrote to use markly gem directly with correct `source_position` API
+  - `commonmarker_merge_example.rb` - Fixed to use `commonmarker/merge` gem properly
+  - `markly_merge_example.rb` - Fixed to use `markly/merge` gem properly
+  - `parslet_toml.rb` - Rewrote to properly use TreeHaver's Parslet backend with language registration
+- **Examples**: Fixed `run_all.rb` test runner
+  - Added parslet example to the test list
+  - Changed markdown examples to use `backend: "standalone"` (they're not TreeHaver backends)
+  - Added MRI+TOML to known incompatibilities (parse returns nil)
+  - Added proper skip reason messages for all known incompatibilities
+- **Examples**: Updated `examples/README.md` documentation
+  - Added Parslet backend section with usage examples
+  - Renamed "Commonmarker Backend" and "Markly Backend" to "Commonmarker (Standalone)" and "Markly (Standalone)"
+  - Clarified that commonmarker and markly are standalone parsers, not TreeHaver backends
+- **Duplicate Constants**: Removed duplicate `CITRUS_DEFAULTS` and `PARSLET_DEFAULTS` definitions
+  - Constants were defined twice in `tree_haver.rb` (lines 170 and 315)
+  - This was causing "already initialized constant" warnings on every require
+
 ## [4.0.5] - 2026-01-09
 
 - TAG: [v4.0.5][4.0.5t]
@@ -1070,7 +1259,11 @@ Despite the major version bump to 3.0.0 (following semver due to the breaking `L
 
 - Initial release
 
-[Unreleased]: https://github.com/kettle-rb/tree_haver/compare/v4.0.5...HEAD
+[Unreleased]: https://github.com/kettle-rb/tree_haver/compare/v5.0.1...HEAD
+[5.0.1]: https://github.com/kettle-rb/tree_haver/compare/v5.0.0...v5.0.1
+[5.0.1t]: https://github.com/kettle-rb/tree_haver/releases/tag/v5.0.1
+[5.0.0]: https://github.com/kettle-rb/tree_haver/compare/v4.0.5...v5.0.0
+[5.0.0t]: https://github.com/kettle-rb/tree_haver/releases/tag/v5.0.0
 [4.0.5]: https://github.com/kettle-rb/tree_haver/compare/v4.0.4...v4.0.5
 [4.0.5t]: https://github.com/kettle-rb/tree_haver/releases/tag/v4.0.5
 [4.0.4]: https://github.com/kettle-rb/tree_haver/compare/v4.0.3...v4.0.4