multi_xml 0.6.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: add5ff8df4d736d143b1d83c38c5f1b8b35d21cd
-  data.tar.gz: ec8e8a3657ff340a9a4abefa2561e44dfee8371d
+SHA256:
+  metadata.gz: d8e4560022692cf83853b50994663cbabfc0bdb943e78c4c2288dff38869bd08
+  data.tar.gz: d25368ffc55f43108708b46cc228e7d4506f44d61cb4d371cdb549fe36bfea2b
 SHA512:
-  metadata.gz: 1cb437e88276aa09e33c5b10a1e32bbf181ecae9543976ab13acc4ca458b00b1315a59f1e3e1cd95fd24e47559a85058585578ba16441ac83c98ffa81c5ee902
-  data.tar.gz: 1931768faabe059174c01e24d12f9b1c8bcc0c9717891ec9ba9098f55c98535ad2a0efab7dcc4bfd756a569f137bf86e4b45b652a182652e6a468393103de9f5
+  metadata.gz: 82885e626a6961ffaa1f34d039ba1a4ac0017c917c46f8232413f020252f9b88873643e44ca7c2b5ad1a7e510c2bccaf3757c246c4c2df801600048ee440f4c1
+  data.tar.gz: 96ea0d4b0947cdeb5230f07687d94be756379a80db7f7fd5e0484ff5a2b1cbc3407eee3c2ea3dce6e49d2595b0daa2f5ab404d20fda5d71fc8dd9bc0bbc7a748

data/.mutant.yml

@@ -0,0 +1,21 @@
+usage: opensource
+
+integration:
+  name: minitest
+
+includes:
+  - lib
+  - test
+
+requires:
+  - multi_xml
+  - mutant/minitest/coverage
+
+matcher:
+  subjects:
+    - MultiXML*
+  ignore:
+    # Platform-specific code path: only triggers on TruffleRuby. Mutant
+    # runs on MRI, so any mutation that touches the RUBY_ENGINE check
+    # produces the same observable behavior as the original.
+    - MultiXML::ParserResolution#skip_on_platform?

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--order random

data/.rubocop.yml

@@ -0,0 +1,65 @@
+require:
+  - standard
+
+plugins:
+  - rubocop-performance
+  - rubocop-rake
+  - rubocop-minitest
+  - standard-performance
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.2
+
+Layout/ArgumentAlignment:
+  EnforcedStyle: with_fixed_indentation
+  IndentationWidth: 2
+
+Layout/ArrayAlignment:
+  EnforcedStyle: with_fixed_indentation
+
+Layout/CaseIndentation:
+  EnforcedStyle: end
+
+Layout/EndAlignment:
+  EnforcedStyleAlignWith: start_of_line
+
+Layout/LineLength:
+  Max: 140
+
+Layout/ParameterAlignment:
+  EnforcedStyle: with_fixed_indentation
+  IndentationWidth: 2
+
+Layout/SpaceInsideHashLiteralBraces:
+  EnforcedStyle: no_space
+
+Metrics/ParameterLists:
+  CountKeywordArgs: false
+
+Style/Alias:
+  EnforcedStyle: prefer_alias_method
+
+Style/EmptyMethod:
+  EnforcedStyle: expanded
+
+Style/FrozenStringLiteralComment:
+  EnforcedStyle: never
+
+Style/RedundantConstantBase:
+  Enabled: false
+
+Style/RescueStandardError:
+  EnforcedStyle: implicit
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/SymbolProc:
+  Enabled: false
+
+Style/TernaryParentheses:
+  EnforcedStyle: require_parentheses_when_complex

data/CHANGELOG.md

@@ -1,3 +1,65 @@
+0.9.1
+-----
+* Fix `MultiXml.method(:load)` resolving to `Kernel#load`. The legacy `MultiXml` constant forwarded calls to `MultiXML` via `method_missing`, but `Module#method` doesn't consult `method_missing`, so `MultiXml.method(:load)` resolved to the inherited `Kernel#load` and crashed with `LoadError` when invoked. Replaces `method_missing` with explicit singleton-method forwarders for every public method on `MultiXML`, mirroring the [analogous fix in MultiJSON](https://github.com/sferik/multi_json/issues/66).
+
+0.9.0
+-----
+* Add `MultiXML.with_parser` for fiber-local scoped parser overrides, matching `MultiJSON.with_adapter`. The override lives in `Fiber[:multi_xml_parser]`, so concurrent fibers and threads each see their own parser without racing on a shared module variable; nested calls save and restore the previous value.
+* Add `MultiXML.parse_options` / `MultiXML.parse_options=` for process-wide default options, matching `MultiJSON.parse_options`. Accepts a `Hash` or a callable (`Proc`/`lambda`); a callable receives the call-site hash as its sole positional argument so defaults can be computed per-call. Defaults merge between `DEFAULT_OPTIONS` and call-site overrides.
+* Introduce `MultiXML::Parser` base module — built-in parsers declare their backend exception class via a `ParseError` constant, matching the `MultiJSON::Adapter` convention. Custom parsers can either extend `MultiXML::Parser` and define `ParseError` or keep defining a `.parse_error` method directly; both styles are accepted.
+* Add `MultiXML::ParserLoadError`, raised when the parser spec is invalid, requiring the parser file raises `LoadError`, or the resolved parser doesn't satisfy the contract (must respond to `.parse` and define either a `ParseError` constant or a `.parse_error` method). Inherits from `ArgumentError` and carries the original exception's class name in its message, matching `MultiJSON::AdapterError`.
+* Rename `MultiXml` constant to `MultiXML` (all caps), matching the style of `MultiJSON`. The old `MultiXml` constant continues to work but emits a one-time deprecation warning on first use and will be removed in v1.0.
+* Add `MultiXML.load` as a deprecated alias for `MultiXML.parse`, matching the style of `MultiJSON.load` → `MultiJSON.parse`. Will be removed in v1.0.
+* Rename the `:symbolize_keys` option to `:symbolize_names`, matching Ruby stdlib's `JSON.parse` and MultiJSON. The old option continues to work but emits a one-time deprecation warning; it will be removed in v1.0.
+* [Add `:namespaces` option to `MultiXML.parse` for consistent namespace handling across parsers](https://github.com/sferik/multi_xml/issues/44) — two modes produce byte-identical output on every backend:
+  * `:strip` (default) — drop xmlns declarations and prefixes; keeps today's libxml/nokogiri output so most users see no change
+  * `:preserve` — keep source prefixes (e.g. `"atom:rel"`) and surface `xmlns` / `xmlns:*` declarations as attributes
+* Fix REXML keeping attribute prefixes (`"gd:etag"`) while other backends stripped them ([#31](https://github.com/sferik/multi_xml/issues/31))
+* Fix Ox prepending namespace prefixes to element names (`"aws:Item"`) when other backends didn't ([#30](https://github.com/sferik/multi_xml/issues/30))
+* Handle namespaced attribute name collisions consistently across backends. When attributes with different prefixes strip to the same local name (e.g. `foo:id` and `bar:id` both becoming `id`), values are collected in an array in document order, with attribute values ahead of any colliding child elements. The libxml SAX parser falls back to its DOM backend in this case since the SAX callback drops attribute prefixes.
+* Fix Ox mixed-content text aggregation in the SAX parser
+* Raise `ArgumentError` on an unknown `:namespaces` mode
+* `undasherize_keys` now runs only in `:strip` mode so prefixed keys aren't rewritten under `:preserve`
+* Reorder `PARSER_PREFERENCE` so `oga` is tried before `rexml`, matching the throughput ranking in the bundled benchmark suite. Affects auto-detection only when neither `ox`, `libxml-ruby`, nor `nokogiri` is available; explicitly selecting a parser is unchanged.
+* Use a TruffleRuby-specific `PARSER_PREFERENCE` ordering (`rexml`, `libxml`, `oga`, `nokogiri`) since TruffleRuby's JIT favors pure-Ruby parsers and penalizes FFI-bound ones. On other engines the default ordering is unchanged.
+* Add a parser benchmark suite (`rake benchmark`) and document per-engine throughput rankings in the README. CI verifies that `PARSER_PREFERENCE` matches the benchmark ranking on MRI, JRuby, and TruffleRuby.
+* Restore JRuby support (dropped in 0.8.0) and add TruffleRuby (native + JVM) to the CI matrix, matching the test coverage of MultiJSON. TruffleRuby is excluded from Windows runners since the `setup-ruby` action doesn't support it there.
+* Add Ruby 4.0 to the CI matrix
+* Support libxml-ruby 6.0.0 by switching from `require "libxml"` (removed in 6.0) to `require "libxml-ruby"`, which is present in both 5.x and 6.x
+* Drop redundant `::Psych::SyntaxError` declaration from the RBS signature to fix a "Different superclasses are specified" type-checking error under rbs v4
+
+0.8.1
+-----
+* [Fix array unwrapping when elements contain nil](https://github.com/sferik/multi_xml/commit/09a875d832c45e2b567889398f45361ec9e36685)
+
+0.8.0
+-----
+* [Add per-parse :parser option to MultiXml.parse](https://github.com/sferik/multi_xml/commit/eb0c1ccadd9026980ba8b6dd0128d6862dc361c4)
+* [Add SAX parsers for Nokogiri and LibXML](https://github.com/sferik/multi_xml/commit/5d67fe6cae3c1ef2c306f1e83fc91b9accfcb724)
+* [Fix inconsistent whitespace handling across parsers](https://github.com/sferik/multi_xml/commit/55aa23f1c401e66984ad1c7d753c1b4258bf0dfd)
+* [Make parsing errors inspectable with cause and xml accessors](https://github.com/sferik/multi_xml/commit/f676f1b657f3352a80ac171d9b839e41ad52a14d)
+* [Drop support for JRuby](https://github.com/sferik/multi_xml/commit/27895ca3918c681ad7ddaa57c5cae7b8340bd601)
+
+0.7.2
+-----
+* [Drop support for Ruby 3.1](https://github.com/sferik/multi_xml/commit/fab6288edd36c58a2b13e0206d8bed305fcb4a4b)
+
+0.7.1
+-----
+* [Relax required Ruby version constraint to allow installation on Debian stable](https://github.com/sferik/multi_xml/commit/7d18711466a15e158dc71344ca6f6e18838ecc8d)
+
+0.7.0
+-----
+* [Add support for Ruby 3.3](https://github.com/sferik/multi_xml/pull/67)
+* [Drop support for Ruby 3.0](https://github.com/sferik/multi_xml/commit/eec72c56307fede3a93f1a61553587cb278b0c8a) [and](https://github.com/sferik/multi_xml/commit/6a6dec80a36c30774a5525b45f71d346fb561e69) [earlier](https://github.com/sferik/multi_xml/commit/e7dad37a0a0be8383a26ffe515c575b5b4d04588)
+* [Don't mutate strings](https://github.com/sferik/multi_xml/commit/71be3fff4afb0277a7e1c47c5f1f4b6106a8eb45)
+
+0.6.0
+-----
+* [Duplexed Streams](https://github.com/sferik/multi_xml/pull/45)
+* [Support for Oga](https://github.com/sferik/multi_xml/pull/47)
+* [Integer unification for Ruby 2.4](https://github.com/sferik/multi_xml/pull/54)
+
 0.5.5
 -----
 * [Fix symbolize_keys function](https://github.com/sferik/multi_xml/commit/a4cae3aeb690999287cd30206399abaa5ce1ae81)

data/Gemfile

@@ -0,0 +1,26 @@
+source "https://rubygems.org"
+
+gem "libxml-ruby", require: nil, platforms: :ruby
+gem "nokogiri", require: nil
+gem "oga", ">= 2.3", require: nil
+gem "ox", require: nil, platforms: :ruby
+gem "rexml", require: nil
+
+gem "minitest", ">= 6"
+gem "minitest-mock", ">= 5.27"
+gem "mutant-minitest", ">= 0.14.1"
+gem "rake", ">= 13.3.1"
+gem "rbs", ">= 4.0.0", platforms: :ruby
+gem "rdoc", ">= 7.0.2"
+gem "rubocop", ">= 1.81.7"
+gem "rubocop-minitest", ">= 0.36"
+gem "rubocop-performance", ">= 1.26.1"
+gem "rubocop-rake", ">= 0.7.1"
+gem "simplecov", ">= 0.22"
+gem "standard", ">= 1.52"
+gem "standard-performance", ">= 1.9"
+gem "steep", ">= 2", platforms: :ruby
+gem "yard", ">= 0.9.38"
+gem "yardstick", ">= 0.9.9"
+
+gemspec

data/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2010-2013 Erik Michaels-Ober
+Copyright (c) 2010-2025 Erik Berlin
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,77 +1,175 @@
 # MultiXML
 
-[![Gem Version](http://img.shields.io/gem/v/multi_xml.svg)][gem]
-[![Build Status](http://img.shields.io/travis/sferik/multi_xml.svg)][travis]
-[![Dependency Status](http://img.shields.io/gemnasium/sferik/multi_xml.svg)][gemnasium]
-[![Code Climate](http://img.shields.io/codeclimate/github/sferik/multi_xml.svg)][codeclimate]
-[![Coverage Status](http://img.shields.io/coveralls/sferik/multi_xml.svg)][coveralls]
+[![Tests](https://github.com/sferik/multi_xml/actions/workflows/tests.yml/badge.svg)][tests]
+[![Linter](https://github.com/sferik/multi_xml/actions/workflows/linter.yml/badge.svg)][linter]
+[![Mutant](https://github.com/sferik/multi_xml/actions/workflows/mutant.yml/badge.svg)][mutant]
+[![Typecheck](https://github.com/sferik/multi_xml/actions/workflows/typecheck.yml/badge.svg)][typecheck]
+[![Docs](https://github.com/sferik/multi_xml/actions/workflows/docs.yml/badge.svg)][docs]
+[![Gem Version](https://badge.fury.io/rb/multi_xml.svg)][gem]
+
+Lots of Ruby libraries parse XML and everyone has their favorite XML parser.
+Instead of choosing a single XML parser and forcing users of your library to
+be stuck with it, you can use MultiXML instead, which will simply choose the
+fastest available XML parser. Here's how to use it:
 
-[gem]: https://rubygems.org/gems/multi_xml
-[travis]: http://travis-ci.org/sferik/multi_xml
-[gemnasium]: https://gemnasium.com/sferik/multi_xml
-[codeclimate]: https://codeclimate.com/github/sferik/multi_xml
-[coveralls]: https://coveralls.io/r/sferik/multi_xml
+```ruby
+require "multi_xml"
+
+MultiXML.parse("<tag>contents</tag>")                         #=> {"tag" => "contents"}
+MultiXML.parse("<tag>contents</tag>", symbolize_names: true)  #=> {tag: "contents"}
+```
+
+`MultiXML.parse` returns `{}` for empty and whitespace-only inputs instead of
+raising, so a missing or blank payload is observable as an empty hash rather
+than an exception. When parsing invalid XML, MultiXML will throw a
+`MultiXML::ParseError`.
+
+```ruby
+begin
+  MultiXML.parse("<open></close>")
+rescue MultiXML::ParseError => exception
+  exception.xml    #=> "<open></close>"
+  exception.cause  #=> Nokogiri::XML::SyntaxError: ...
+end
+```
+
+### Deprecated in 0.9.0
+
+The module constant, the primary parse entry point, and the
+symbolize-keys option were renamed to align MultiXML with MultiJSON
+and Ruby stdlib `JSON.parse`. The old names still work in 0.x but
+now emit a one-time deprecation warning; they will be removed in 1.0.
 
-A generic swappable back-end for XML parsing
+| Deprecated                    | Use instead                     |
+| ----------------------------- | ------------------------------- |
+| `MultiXml` (constant)         | `MultiXML` (all-caps)           |
+| `MultiXML.load(xml)`          | `MultiXML.parse(xml)`           |
+| `symbolize_keys:` option      | `symbolize_names:` option       |
 
-## Installation
-    gem install multi_xml
+The `MultiXml` constant (CamelCase) continues to work as a thin
+delegator; every method call, constant lookup, and rescue clause
+routes through `MultiXML` transparently.
 
-## Documentation
-[http://rdoc.info/gems/multi_xml][documentation]
+`ParseError` instances expose `xml` and `cause` readers. `xml` contains the
+input that caused the problem; `cause` contains the original exception raised
+by the underlying parser.
 
-[documentation]: http://rdoc.info/gems/multi_xml
+### Writing a custom parser
+
+A custom parser is any class (or module) that responds to two class methods:
 
-## Usage Examples
-Lots of Ruby libraries utilize XML parsing in some form, and everyone has their
-favorite XML library. In order to best support multiple XML parsers and
-libraries, `multi_xml` is a general-purpose swappable XML backend library. You
-use it like so:
 ```ruby
-require 'multi_xml'
+class MyParser
+  def self.parse(io, namespaces: :strip)
+    # parse the IO-like object into a Hash, raising ParseError on failure
+  end
 
-MultiXml.parser = :ox
-MultiXml.parser = MultiXml::Parsers::Ox # Same as above
-MultiXml.parse('<tag>This is the contents</tag>') # Parsed using Ox
+  def self.parse_error
+    MyParser::ParseError
+  end
+end
 
-MultiXml.parser = :libxml
-MultiXml.parser = MultiXml::Parsers::Libxml # Same as above
-MultiXml.parse('<tag>This is the contents</tag>') # Parsed using LibXML
+MultiXML.parser = MyParser
+```
 
-MultiXml.parser = :nokogiri
-MultiXml.parser = MultiXml::Parsers::Nokogiri # Same as above
-MultiXml.parse('<tag>This is the contents</tag>') # Parsed using Nokogiri
+`parse_error` is required: `MultiXML.parse` rescues `MyParser.parse_error`
+to wrap parse failures in `MultiXML::ParseError`. The built-in parsers in
+`lib/multi_xml/parsers/` are working examples.
+
+MultiXML tries to have intelligent defaulting. If any supported library is
+already loaded, MultiXML uses it before attempting to load others. When no
+backend is preloaded, MultiXML walks its automatic preference list and uses the first
+one that loads successfully:
+
+1. [`ox`][ox]
+2. [`libxml-ruby`][libxml-ruby]
+3. [`nokogiri`][nokogiri]
+4. [`oga`][oga]
+5. [`rexml`][rexml]
+
+This is the library's built-in default selection order, not a guarantee that
+the list is globally fastest for every workload. Real-world performance depends
+on the document shape and the Ruby implementation, and the benchmark suite
+below also measures SAX backends that are not part of automatic parser
+detection. REXML is a Ruby default gem, so it's always available as a
+last-resort fallback on any supported Ruby. If you have a workload where a
+different backend is faster, set it explicitly with
+`MultiXML.parser = :your_parser`.
+
+## Benchmarking Parsers
+
+This repo includes a benchmark suite that compares every available built-in
+backend across multiple XML shapes and sizes instead of relying on a single
+synthetic document. The workloads cover:
+
+- shallow and wide XML
+- deeply nested XML
+- record batches with repeated siblings
+- attribute-dense elements
+- mixed-content sections
+- namespace-heavy feeds
+- a large catalog-style document
+
+Run the full benchmark with:
+
+```bash
+bundle exec rake benchmark
+```
 
-MultiXml.parser = :rexml
-MultiXml.parser = MultiXml::Parsers::Rexml # Same as above
-MultiXml.parse('<tag>This is the contents</tag>') # Parsed using REXML
+You can also run the script directly for shorter runs or Markdown-friendly
+output:
 
-MultiXml.parser = :oga
-MultiXml.parser = MultiXml::Parsers::Oga # Same as above
-MultiXml.parse('<tag>This is the contents</tag>') # Parsed using Oga
+```bash
+bundle exec ruby benchmark.rb --quick
+bundle exec ruby benchmark.rb --format=markdown
 ```
-The `parser` setter takes either a symbol or a class (to allow for custom XML
-parsers) that responds to `.parse` at the class level.
 
-MultiXML tries to have intelligent defaulting. That is, if you have any of the
-supported parsers already loaded, it will utilize them before attempting to
-load any. When loading, libraries are ordered by speed: first Ox, then LibXML,
-then Nokogiri, and finally REXML.
+The output includes:
+
+- a single best-overall parser based on the equal-weight geometric mean of
+  per-scenario relative throughput
+- an overall ranking table for every parser
+- a scenario matrix showing which parser won each workload
+- an exclusions table when a parser crashes or produces mismatched output on a
+  valid workload
+
+Allocation efficiency is reported as a secondary metric using allocated Ruby
+objects per parse so ties on throughput are easier to interpret.
+
+`PARSER_PREFERENCE` drives auto-detection (see "Configuration" above) and is
+ordered fastest-first per the benchmark suite. CI re-runs the benchmark on
+each supported runtime and fails if the observed ranking diverges from this
+table:
+
+| rank | CRuby/MRI  | JRuby      | TruffleRuby |
+| ---- | ---------- | ---------- | ----------- |
+| 1    | `ox`       | —          | —           |
+| 2    | `libxml`   | —          | `rexml`     |
+| 3    | `nokogiri` | `nokogiri` | `libxml`    |
+| 4    | `oga`      | —          | `oga`       |
+| 5    | `rexml`    | `rexml`    | `nokogiri`  |
+
+A dash means the parser isn't usable on that runtime. `ox` has no JRuby
+build and is filtered out of TruffleRuby auto-detection (its SAX callbacks
+miscompile under the JIT after warmup); `libxml-ruby` has no JRuby build;
+`oga` 3.x crashes on JRuby 10 (its precompiled Java backend was built
+against an older JRuby API). TruffleRuby's JIT inverts the FFI-vs-pure-Ruby
+tradeoff for the remaining backends, so `rexml` rises to the top and
+`nokogiri` falls to last.
 
 ## Supported Ruby Versions
-This library aims to support and is [tested against][travis] the following Ruby
-implementations:
 
-* Ruby 1.9.3
-* Ruby 2.0.0
-* Ruby 2.1
-* Ruby 2.2
-* Ruby 2.3
-* [JRuby 9000][jruby]
+This library aims to support and is [tested against](https://github.com/sferik/multi_xml/actions/workflows/tests.yml) the following Ruby
+implementations:
 
-[jruby]: http://jruby.org/
+- Ruby 3.2
+- Ruby 3.3
+- Ruby 3.4
+- Ruby 4.0
+- [JRuby][jruby] 10.0 (targets Ruby 3.4 compatibility)
+- [TruffleRuby][truffleruby] 33.0 (native and JVM)
 
-If something doesn't work on one of these interpreters, it's a bug.
+If something doesn't work in one of these implementations, it's a bug.
 
 This library may inadvertently work (or seem to work) on other Ruby
 implementations, however support will only be provided for the versions listed
@@ -84,12 +182,38 @@ implementation, you will be responsible for providing patches in a timely
 fashion. If critical issues for a particular implementation exist at the time
 of a major release, support for that Ruby version may be dropped.
 
-## Inspiration
-MultiXML was inspired by [MultiJSON][].
+## Versioning
 
-[multijson]: https://github.com/intridea/multi_json/
+This library aims to adhere to [Semantic Versioning 2.0.0][semver]. Violations
+of this scheme should be reported as bugs. Specifically, if a minor or patch
+version is released that breaks backward compatibility, that version should be
+immediately yanked and/or a new version should be immediately released that
+restores compatibility. Breaking changes to the public API will only be
+introduced with new major versions. As a result of this policy, you can (and
+should) specify a dependency on this gem using the [Pessimistic Version
+Constraint][pvc] with two digits of precision. For example:
+
+```ruby
+spec.add_dependency "multi_xml", "~> 0.9"
+```
 
 ## Copyright
-Copyright (c) 2010-2013 Erik Michaels-Ober. See [LICENSE][] for details.
 
+Copyright (c) 2010-2026 Erik Berlin. See [LICENSE][license] for details.
+
+[docs]: https://github.com/sferik/multi_xml/actions/workflows/docs.yml
+[gem]: https://rubygems.org/gems/multi_xml
+[jruby]: http://www.jruby.org/
+[libxml-ruby]: https://github.com/xml4r/libxml-ruby
 [license]: LICENSE.md
+[linter]: https://github.com/sferik/multi_xml/actions/workflows/linter.yml
+[mutant]: https://github.com/sferik/multi_xml/actions/workflows/mutant.yml
+[nokogiri]: https://nokogiri.org/
+[oga]: https://gitlab.com/yorickpeterse/oga
+[ox]: https://github.com/ohler55/ox
+[pvc]: http://docs.rubygems.org/read/chapter/16#page74
+[rexml]: https://github.com/ruby/rexml
+[semver]: http://semver.org/
+[tests]: https://github.com/sferik/multi_xml/actions/workflows/tests.yml
+[truffleruby]: https://www.graalvm.org/ruby/
+[typecheck]: https://github.com/sferik/multi_xml/actions/workflows/typecheck.yml

data/Rakefile

@@ -0,0 +1,68 @@
+require "bundler/gem_tasks"
+require "shellwords"
+
+# Override release task to skip gem push (handled by GitHub Actions with attestations)
+Rake::Task["release"].clear
+desc "Build gem and create tag (gem push handled by CI)"
+task release: %w[build release:guard_clean release:source_control_push]
+
+require "rake/testtask"
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+end
+
+require "standard/rake"
+require "rubocop/rake_task"
+RuboCop::RakeTask.new
+
+require "yard"
+YARD::Rake::YardocTask.new do |task|
+  task.files = ["lib/**/*.rb", "-", "LICENSE.md"]
+  task.options = [
+    "--no-private",
+    "--protected",
+    "--output-dir", "doc/yard",
+    "--markup", "markdown"
+  ]
+end
+
+require "yardstick/rake/measurement"
+Yardstick::Rake::Measurement.new do |measurement|
+  measurement.output = "measurement/report.txt"
+end
+
+require "yardstick/rake/verify"
+Yardstick::Rake::Verify.new do |verify|
+  verify.threshold = 100
+end
+
+# Steep requires native extensions not available on JRuby or Windows
+unless RUBY_PLATFORM == "java" || Gem.win_platform?
+  require "steep/rake_task"
+  Steep::RakeTask.new
+end
+
+desc "Run linters"
+task lint: %i[rubocop standard]
+
+desc "Benchmark available XML parsers across representative workloads"
+task :benchmark do
+  args = ENV["BENCHMARK_ARGS"] ? Shellwords.split(ENV["BENCHMARK_ARGS"]) : []
+  sh Gem.ruby, "benchmark.rb", *args
+end
+
+# Mutant uses fork() which is not available on Windows or JRuby
+desc "Run mutation testing"
+task :mutant do
+  if Gem.win_platform? || RUBY_PLATFORM == "java"
+    puts "Skipping mutant on Windows/JRuby (fork not supported)"
+  else
+    system("bundle", "exec", "mutant", "run") || exit(1)
+  end
+end
+
+default_tasks = %i[test lint verify_measurements mutant]
+default_tasks << :steep unless RUBY_PLATFORM == "java" || Gem.win_platform?
+
+task default: default_tasks

data/Steepfile

@@ -0,0 +1,29 @@
+D = Steep::Diagnostic
+
+target :lib do
+  signature "sig"
+
+  # Check core library files (excluding parser implementations that depend on optional gems)
+  check "lib/multi_xml.rb"
+  check "lib/multi_xml/constants.rb"
+  check "lib/multi_xml/errors.rb"
+  check "lib/multi_xml/file_like.rb"
+  check "lib/multi_xml/helpers.rb"
+  check "lib/multi_xml/version.rb"
+
+  # Use stdlib types
+  library "date"
+  library "time"
+  library "yaml"
+  library "bigdecimal"
+  library "stringio"
+
+  configure_code_diagnostics(D::Ruby.strict) do |hash|
+    # The fiber-local Fiber[] reader returns untyped — intentional
+    # for with_parser's previous_override save/restore.
+    hash[D::Ruby::FallbackAny] = :hint
+    # set_backtrace has three overloads and Steep can't pick one when
+    # given an `(Array[String] | nil)` union from `cause.backtrace`.
+    hash[D::Ruby::UnresolvedOverloading] = :hint
+  end
+end

data/benchmark/overall_parser_benchmark.rb

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require_relative "../benchmark"
+
+exit MultiXMLBenchmark.run(ARGV)