tree_haver 4.0.5 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3f6764cb2c0399f4255cc4536745156cd8391fa1818b9b84db9d0b39ca17fa9
-  data.tar.gz: d9e12364a4480307b8cd8a7ca0315bbeba7764c6bfe20747b3b8ff792e9fe2e7
+  metadata.gz: c483d5a811ccb8c64191bc8341e94ecc41996d1aab8a78ef81fea2833231a048
+  data.tar.gz: 0c0e1ef09ac515f0faf00d8d5f88568acd573007bd31a94d04706f8016cedf86
 SHA512:
-  metadata.gz: 6a95af29f397cea98bc29a93885f9285637ae82469417b62c981629d21861f5b64560ca0e2c21b0405abdc541d04b39f6c1848928273b82679ba3f169f885549
-  data.tar.gz: bbd048585aed007eed86bdd117b18cff1e72e378fd20bbc07a252b6095ab38d4c5c9eb83fc572c21bcd07e515b2ad1bfae50f9705b75f69f4d955ecf65d4b844
+  metadata.gz: 98548924f413e5ee8c39bd35af68debb5f3463c088768d991635ad50f2dc649231c60ff8cae12efce4569bfbfbdd61ed2873a225fbcbb6289930490a7ec6a195
+  data.tar.gz: edaa9affbcc349cf59dd57b02821345e4319d6666fcf01fcbfb8bd0eb490010545ff38aa175b108f0178aa24c8ca0573f653a5adc91449cd834b71aff7ac9acc

data/CHANGELOG.md

@@ -30,6 +30,147 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [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 +1211,9 @@ 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.0...HEAD
+[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