makiri 0.15.0-aarch64-linux → 0.17.0.rc1-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9bef2471bfcd87d3e3c31bf6f4eeecef71202d81bf0bb46b7b71eee526cd1a4
-  data.tar.gz: 1836c1d1ee430cba8a058d63411259483ad84f3f4a1fdb69aae53621f1093f68
+  metadata.gz: 8710995de3498cde22ec02966971c541ba7ba3f2c9176be2566c93008bdcd82d
+  data.tar.gz: b6fd0ff75de338b8cab9b7c3ec74edd471ba64c17094ebcb50e3432818820172
 SHA512:
-  metadata.gz: 3f8c5b7d20a0190f05afd7e1d8c453979eeaf3dc7d1ec58e5314fdeb803e84d5a3bbbf6e1fa533b3827d0bc70b8b41269d5a5d2d06d79339c1244e3a5a10b7a4
-  data.tar.gz: e93f2d6a31337fc9e23782b4e3e5a37196e5ef95a92b206868721f8dc04d0263a593eb5361fef0c2fa0a67ab037a3777faafb65bcbe06fa0f45bdf215430bdd1
+  metadata.gz: 173b0f7471ff9c615421b91ab848326990b8c9706c54cbc2049b216b1d71c15147b950f73a323ddb2e13a0580d7644453a61476cff46952cf4419c25233a2d95
+  data.tar.gz: 63d50aab4ee8a15570215b275a566d1dbbc1b11ad22551564cc5e790821711ea57feee4432c1bf28e18a3c1e2aa0251b6a30433df562aae7cfd84e6b580acfb8

data/CHANGELOG.md

@@ -1,5 +1,121 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.17.0.rc1] - 2026-10-22
+
+### Added
+
+* `Makiri::Lexbor::CSS.parse_stylesheet` returns the declarations in an
+  at-rule's block (`@font-face`, `@page`, ...) as its `:declarations`; they
+  were dropped.
+
+### Changed
+
+* HTML is parsed by Makiri's own Rust port of Lexbor's tokenizer and tree
+  builder, into a DOM of Makiri's own, and the CSS selector and stylesheet
+  parsers are ported too. A parsed document takes about 40% less memory.
+* Installing from source needs Rust 1.84 or newer (and libclang), and no
+  longer CMake: the gem carries none of Lexbor's sources, only its LICENSE
+  and NOTICE.
+* `Makiri::XML`'s `#css`, `#at_css` and `#matches?` run on the same matcher
+  as HTML's and answer as a browser's `querySelectorAll` does in an XML
+  document, 10-20x faster on compound selectors (`.item`, `ul li.item`).
+  This changes some answers:
+  * a bare type selector (`p`) matches that name in any namespace;
+  * the root element's namespace declarations are no longer picked up: a
+    prefix must be given in the ns Hash, whose `"xmlns"` entry is the
+    default namespace (on HTML too);
+  * a selector run on a node may match through ancestors outside it
+    (`node.css("body p")`); only the node's descendants are returned;
+  * `[a=v i]`, `:nth-child(... of S)`, and the form-state and link
+    pseudo-classes on XHTML elements are supported;
+  * `||` and `:current()` raise `Makiri::CSS::SyntaxError`, and an over-long
+    chain `Makiri::Error` (it was `Makiri::XPath::LimitExceeded`).
+* HTML `css(selector, ns)` resolves namespace prefixes: `svg|path` is the SVG
+  `path`, `|p` an element in no namespace, `[x|href]` the attribute in `x`'s
+  namespace. A prefix the Hash does not bind raises
+  `Makiri::CSS::SyntaxError`; prefixes used to be ignored.
+* HTML parsing follows the HTML Standard where Lexbor did not. This affects
+  malformed or unusual markup only: `<frameset>`, `<form>` and tables inside
+  `<template>`, `<![CDA` or `<!` at the end of the input, the adoption
+  agency, `<textarea>`, `<input type=HIDDEN>` and `<image>` in a table,
+  `<sup>` in SVG or MathML, and a repeated attribute name (the first is
+  kept). Fragment parsing (`#inner_html=`, `#outer_html=`, `Node#parse`,
+  `context:` given an element) takes the context element's quirks mode,
+  namespace and ancestor `<form>` into account, as browsers do.
+* CSS selectors are parsed as Selectors 4 says: `:has()` inside `:has()` and
+  an invalid argument to `:has()` make the selector invalid, an empty
+  `:is()` / `:where()` is valid and matches nothing, and `#1a` is not an ID
+  selector.
+* `parse_stylesheet` reads names and values by one rule for every property: a
+  declaration name is lower-cased unless it is a custom property, an at-rule
+  name is lower-cased, and a value is the text as written with whitespace
+  runs collapsed (`color: RED` stays `RED`; it came back as `red`).
+  `:specificity` is counted as Selectors 4 does (`:is()` / `:not()` /
+  `:has()` take their most specific argument).
+
+### Removed
+
+* The 10,000-`<option>` limit on a `<select>`: a select with any number of
+  options parses in linear time, as browsers parse it.
+
+### Fixed
+
+* `parse_stylesheet` keeps a rule such as `a:hover { ... }` inside `@media`
+  or `@supports`; it was read as a declaration, which dropped that rule and
+  every one after it in the block. A comment between a declaration's name
+  and its `:` no longer drops the declarations that follow.
+* A namespaced type selector in the middle of a compound (`.x|a`) raises
+  `Makiri::CSS::SyntaxError`, as browsers do.
+* `:any-link` / `:link` match only an HTML `a` or `area`, or an SVG `a`, with
+  an `href` (`<link href>` and `<map>` matched). `:read-write` /
+  `:read-only` follow the HTML Standard (a checkbox is read-only, an element
+  inside `contenteditable` is read-write), and `:empty` ignores processing
+  instructions.
+* HTML's `:nth-child` family counts element siblings only:
+  `html:first-child` matched nothing after `<!doctype html>`.
+* An attribute keeps the namespace it was made in: `set_attribute_ns` in the
+  element's own namespace replaces the attribute it set before instead of
+  adding a second, and an attribute removed from its element keeps its
+  `namespace_uri`.
+* An attribute name is serialized in the case it was set (`e["viewBox"]` on
+  an element in no namespace was written lower-cased).
+* A void element's `#inner_html` is empty even when it has children, and a
+  prefixed HTML, SVG or MathML element is written by its local name.
+* `Node#line` of a void element fostered out of a table is its line, not nil.
+* Many namespaces created with `create_element_ns` no longer make lookups
+  quadratic.
+* `HTML::Document#import_node` given a document raises "cannot import a
+  document; use #dup", as `#clone_node` does.
+
+## [0.16.0] - 2026-10-10
+
+### Added
+
+* `Makiri::NATIVE_VERSION` and `Makiri::NATIVE_RUBY_API_VERSION`: the gem
+  version and Ruby `MAJOR.MINOR` the native extension was built as.
+  `require "makiri"` raises `LoadError` for an extension built for another
+  Ruby (refused by the extension itself, before it defines anything) or as
+  another makiri version (e.g. a stale `lib/makiri/makiri.bundle` in a
+  checkout).
+* `Node#child_count`, `#child_at(i)`, `#element_child_count` and
+  `#element_child_at(i)` (HTML and XML): count and index a child list without
+  building `#children`. A loop over the indexes in order costs O(1) a step,
+  also while other lists are read in between. Any child-list edit in the
+  document resets that, so a loop that edits as it indexes walks from the
+  nearer end after each edit. `child_at` returns nil for a negative index or
+  one past the end.
+* `Node#first_child` (an alias of `#child`) and `#last_child`.
+* `Node#root_node`, DOM `getRootNode()`: the Document, a DocumentFragment, or
+  the top of a detached subtree. An Attr is its own root.
+
+### Changed
+
+* `#local_name`, `#prefix`, `#namespace_uri` and `#tag_name` return frozen,
+  interned Strings: every read of one name returns the same object. `#name`
+  still returns a new, mutable String.
+
 ## [0.15.0] - 2026-10-09
 
 ### Added

data/NOKOGIRI_DIFFERENCES.md

@@ -149,7 +149,7 @@ what browsers do - rather than libxml2. Detailed, test-backed notes live in
 * `<?php ... ?>` in HTML input is a **ProcessingInstruction** node; `#to_html`
   writes it back as `<?php ... ?>`, and `<?` at end of input is ignored.
   * The HTML Standard added processing-instruction tokens and tree-construction
-    rules for them; Makiri follows them through Lexbor. `Nokogiri::HTML5` (gumbo)
+    rules for them, and Makiri's parser follows them. `Nokogiri::HTML5` (gumbo)
     still produces the older bogus comment (`<!--?php ... ?-->`), and
     `Nokogiri::HTML` (libxml2) its own comment.
 
@@ -158,17 +158,14 @@ what browsers do - rather than libxml2. Detailed, test-backed notes live in
   Nokogiri's. `inner_html=`, `outer_html=` and `Node#parse` take no keyword.
   `Nokogiri::HTML` (libxml2) instead stops at depth 256 and returns the
   truncated document.
-* More than 10,000 `<option>`s in one `<select>` raise `Makiri::Error`;
-  Nokogiri has no such limit.
 
 ## HTML mutation
 
 * There is no `Node#name=` / `#node_name=` (on HTML or XML nodes). Nokogiri
   renames a node in place and keeps its identity; the DOM has no rename, and
-  Lexbor keeps elements such as `<template>`, `<option>` and `<style>` in
-  structs of their own, so a node cannot change its tag safely. Create an
-  element of the new name, move the attributes and children, and `replace`
-  the old one (see CHANGELOG.md).
+  an element's tag decides what it is (a `<template>` owns its contents), so a
+  node cannot change its tag. Create an element of the new name, move the
+  attributes and children, and `replace` the old one (see CHANGELOG.md).
 * Element and attribute names follow the WHATWG DOM's rules
   * `create_element`, `[]=` and `set_attribute_ns` raise `ArgumentError` for a
     name the DOM refuses - one holding whitespace, `/`, `>` (or `=` for an
@@ -224,26 +221,19 @@ what browsers do - rather than libxml2. Detailed, test-backed notes live in
   * One exception to the DOM: an HTML attribute named `xml:lang` (in no
     namespace) becomes the XML namespace's `xml:lang`, as the XML reader reads
     that name, so XHTML-style HTML still writes as XML.
-* A known gap, in Lexbor's tag table: an HTML document that already holds a
-  parsed element named with a colon (`<x:y>`, one local name) and then
-  receives, by `import_node` from another document, a prefixed element
-  written the same way (`x:y` from XML: prefix `x`, local name `y`) re-points
-  the table's entry for that spelling - the parsed element then no longer
-  matches CSS `x\:y`. Copies within one document do not touch the table.
 * An XML element with a prefix, imported into HTML, keeps it (`h:div` in
   XHTML has the local name `div`). Two readers then disagree, as they do in
-  browsers: CSS's `div` matches it (Lexbor matches the local name), XPath's
-  `//div` does not (an HTML element's name test reads its qualified name). And
-  Lexbor's HTML serializer writes the prefix (`<h:div>`), where the HTML
-  standard writes the local name, so the HTML does not re-parse to the same
-  element.
+  browsers: CSS's `div` matches it (the matcher compares the local name),
+  XPath's `//div` does not (an HTML element's name test reads its qualified
+  name). `#to_html` writes the local name (`<div>`), as the HTML standard
+  does.
 
 ## CSS
 
 * Most jQuery/Nokogiri CSS extensions are not supported (`:gt`, `:lt`, `:eq`, `:first`, ...)
-  * Makiri uses Lexbor's selector engine, which is standards-based apart from one
-    text-containment extension. Use XPath (`xpath("//p[contains(., 'x')]")`) or
-    Enumerable (`css('li')[1]`) for the rest.
+  * Makiri's selector engine is standards-based. Use XPath
+    (`xpath("//p[contains(., 'x')]")`) or Enumerable (`css('li')[1]`) for the
+    rest.
     Standard Level-4 selectors (`:is` / `:where` / `:has`) are supported; some of which Nokogiri rejects.
   * There is no text-containment pseudo-class. Nokogiri's `:contains()` is
     not supported, and neither is Lexbor's `:lexbor-contains()`: it raises
@@ -255,33 +245,45 @@ what browsers do - rather than libxml2. Detailed, test-backed notes live in
   selector) is supported and correct on both HTML and XML - the "type" is the
   element's own expanded name.
   * Nokogiri (XML and HTML5) mistranslates these to first-/only-child
-    (`//*[position()=1]` / `//*[last()=1]`), so it under-matches; Makiri matches
-    Lexbor's HTML matcher.
-* HTML CSS takes a `{prefix => uri}` Hash (`css(selector, ns)`) but does not
-  resolve prefixes against it: Lexbor's matcher matches a prefixed type selector
-  loosely, so `svg|path`, `|path` and `path` all find the SVG element whatever
-  is bound. `Nokogiri::HTML5` honours the binding (a wrong URI finds nothing).
-  * The Hash is accepted and unused rather than refused, so the `css(selector,
-    ns)` a caller writes for both representations works. Use `#xpath`, where a
-    prefix IS resolved against the bindings, when the namespace matters.
-  * `Makiri::XML` resolves CSS prefixes properly - it lowers the selector to the
-    XPath engine, which registers the bindings.
-  * The same holds for attribute selectors: HTML `[|href]` (no namespace) and
-    plain `[href]` also find an SVG `xlink:href`, which `Nokogiri::HTML5`
-    does not.
-    `Makiri::XML` reads `[|a]` as the no-namespace attribute.
+    (`//*[position()=1]` / `//*[last()=1]`), so it under-matches; Makiri does
+    not.
+* CSS resolves a namespace prefix against the `{prefix => uri}` Hash
+  (`css(selector, ns)`), on HTML and XML alike: `svg|path` is the SVG `path`
+  once `svg` is bound, `|path` an element in no namespace, and a prefix the
+  Hash does not bind raises `Makiri::CSS::SyntaxError`. `[x|href]` finds the
+  XLink `href` once `x` is bound to XLink. The Hash's `"xmlns"` entry is the
+  default namespace, as CSS `@namespace` without a prefix sets one: a type or
+  universal selector without a prefix is then in it.
+  * Without a default, a bare type selector matches its name in any namespace
+    (`path` finds the SVG element, `entry` an Atom entry), as a browser's
+    `querySelectorAll` does. `Nokogiri::XML` binds a bare name to the root's
+    default namespace when no Hash is given, and to no namespace once one is;
+    pass `"xmlns" => uri` (or `"xmlns" => ""`) for that reading.
+  * `Makiri::XML` does not collect the document's own declarations: a prefix
+    is declared by the Hash or not at all. `Nokogiri::XML` collects the
+    root's.
+  * A bare `*` under a default namespace is in it, as CSS has it;
+    `Nokogiri::XML` matches any element.
+  * Up to 0.16 HTML accepted the Hash and ignored every prefix, and
+    `Makiri::XML` collected the root's declarations as Nokogiri does.
 * A selector under a node matches the way `Element#querySelectorAll` does in a
-  browser, not scoped to that node, on HTML: `at_css("#c").css("div p")` finds a
-  `p` inside `#c` when `#c` is itself a `div`, since the selector is matched
-  against the whole document and only the results are kept to descendants.
-  `Nokogiri::HTML5` and `Nokogiri::XML` scope the selector to the node (`#c`
-  cannot be the `div`), and so does `Makiri::XML`, which lowers the selector to
-  an XPath from the node. Lexbor has no `:scope`; for a scoped match on HTML,
-  use XPath from the node (`xpath(".//div//p")`).
-* The attribute case modifiers (`[a="x" i]`, `[a="x" s]`): HTML supports both,
-  through Lexbor's matcher. `Makiri::XML` accepts `s` (case-sensitive, which XML
-  values are anyway) and refuses `i` with `Makiri::CSS::SyntaxError`. Nokogiri
-  refuses both on either representation.
+  browser, not scoped to that node, on HTML and XML alike:
+  `at_css("#c").css("div p")` finds a `p` inside `#c` when `#c` is itself a
+  `div`, since the selector is matched against the whole tree and only the
+  results are kept to descendants. `Nokogiri::HTML5` and `Nokogiri::XML` scope
+  the selector to the node (`#c` cannot be the `div`), and so did
+  `Makiri::XML` up to 0.16. There is no `:scope`; for a scoped match, use XPath
+  from the node (`xpath(".//div//p")`).
+* The attribute case modifiers (`[a="x" i]`, `[a="x" s]`) are supported on
+  both representations. Nokogiri refuses both on either.
+* The form-state and link pseudo-classes (`:checked`, `:disabled`,
+  `:enabled`, `:required`, `:optional`, `:placeholder-shown`, `:link`, ...)
+  answer on `Makiri::XML` too, for XHTML elements, as browsers do in an XML
+  document; on any other element they match nothing. `Nokogiri::XML` refuses
+  them.
+* A selector `Makiri` cannot run (the column combinator `||`, `:current()`)
+  raises `Makiri::CSS::SyntaxError`, as a browser's `querySelectorAll` throws a
+  SyntaxError, on both representations.
 * `#matches?` answers for a DETACHED node (`document.create_element("p")
   .matches?("p")` is true, on both representations). Nokogiri raises
   `NoMethodError` there - it implements `#matches?` as a search from
@@ -294,7 +296,9 @@ what browsers do - rather than libxml2. Detailed, test-backed notes live in
   therefore matches no type selector.
   * `Nokogiri::HTML5` is case-sensitive on HTML elements too, so `LI` does not
     match `<li>` there. `Makiri::XML`'s `#css` is case-sensitive, as XML names
-    are.
+    are - an XHTML element's included, as in a browser's XML document - and so
+    are its attribute values, the HTML Standard's case-insensitive list of
+    attributes applying only to an HTML document.
 
 ## Serialization
 

data/NOTICE

@@ -8,6 +8,13 @@ This product includes software developed by:
   Licensed under the Apache License, Version 2.0
   https://lexbor.com / https://github.com/lexbor/lexbor
 
+  The HTML tokenizer and tree builder under ext/makiri/rust/src/html/ and the
+  CSS syntax, selector and stylesheet parser under
+  ext/makiri/rust/src/selectors/ are Rust ports of Lexbor's, as are the HTML
+  CSS matcher under ext/makiri/rust/src/css_match/ and the tag and
+  attribute tables generated from Lexbor's. The extension links no Lexbor
+  code; Lexbor's LICENSE and NOTICE are kept under vendor/lexbor/ in the gem.
+
 The XPath 1.0 engine under ext/makiri/rust/src/xpath/ is an original
 implementation written for this project. No code is derived from libxml2 or
 libxslt.

data/README.md

@@ -28,8 +28,7 @@ XPath 1.0 evaluation in its own native engine, with no libxml2 dependency.
     differential, and property-based testing vs Nokogiri (see below).
 * Bounded, fail-closed execution
   * XPath evaluation is bounded by per-evaluation limits on work, memory, and recursion.
-  * HTML parsing bounds the tree depth (`max_tree_depth:`, default 400) and the
-    `<option>`s per `<select>` (10,000).
+  * HTML parsing bounds the tree depth (`max_tree_depth:`, default 400).
   * Ownership and borrowing are kept explicit across layers, with owned/borrowed
     string types and verified text at engine boundaries.
   * Programmatic invalid input, limit violations, allocation failures, and unsupported constructs
@@ -109,9 +108,10 @@ el = doc.at_xpath("//a:entry", ns)
 el.local_name                                  # => "entry"
 el.namespace_uri                               # => "http://www.w3.org/2005/Atom"
 
-# CSS selectors work too (lowered to the native XPath engine): a bare type
-# selector binds to the document's default namespace, so this just works.
+# CSS selectors work too, as in a browser: a bare type selector matches its
+# name in any namespace, so this just works.
 doc.css("entry").length                        # => 2
+doc.css("a|entry", ns).length                  # => 2 (a prefix the Hash binds)
 doc.css("feed > entry").map { |e| e.at_css("title").text }  # => ["Hello", "World"]
 
 # Serialize back to XML
@@ -256,10 +256,13 @@ See also [`spec/conformance/README.md`](spec/conformance/README.md).
 ## Requirements
 
 * CRuby 3.2 or newer.
-* A Rust toolchain (stable) with `cargo` - the extension is a Rust crate.
+* Rust 1.84 or newer with `cargo` - the extension is a Rust crate. (Binary
+  gems are published for the common platforms, which need no toolchain.)
 * libclang (clang's development library): rb-sys runs bindgen at build time and
   reads Ruby's headers through it.
-* CMake and a C toolchain, to build the vendored Lexbor static library.
+
+Development also needs CMake and a C toolchain, to build the vendored Lexbor
+that the Rust port is tested against (`rake lexbor`).
 
 ## Build (development)
 

data/lib/makiri/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Makiri
-  VERSION = "0.15.0"
+  VERSION = "0.17.0.rc1"
 end

data/lib/makiri/xml/node_methods.rb

@@ -28,30 +28,33 @@ module Makiri
       # After #key?, which #has_attribute? aliases.
       ReaderAliases.define_on(self)
 
-      # CSS selector queries over XML, lowered to the native XPath engine (so
-      # matching is case-sensitive and namespace-aware, unlike a Lexbor HTML
-      # matcher). Nokogiri-compatible namespaces: the root element's
-      # declarations are collected automatically (a bare type selector binds to
-      # the default namespace), unless an +ns+ hash of {prefix => uri} is
-      # given, which then replaces them.
+      # CSS selector queries over XML, matched by the same engine as HTML's,
+      # as a browser's querySelectorAll matches them in an XML document: names
+      # and values compare as written, a type selector without a prefix
+      # matches its name in any namespace, and the context node's ancestors
+      # take part in the match while only its descendants are returned. An
+      # +ns+ hash of {prefix => uri} declares the prefixes the selector may
+      # use; its "xmlns" entry, if any, is the default namespace a bare type
+      # selector is then in.
       #
-      #   doc.css("entry")               # default-namespace bound (Atom/RSS just work)
-      #   doc.css("a|entry", "a" => uri) # explicit prefix
+      #   doc.css("entry")                    # <entry> in any namespace
+      #   doc.css("a|entry", "a" => uri)      # <entry> in uri
+      #   doc.css("entry", "xmlns" => uri)    # the same, as a default
       #
       # @return [Makiri::NodeSet]
       def css(selector, ns = nil)
-        _css(selector.to_s, _css_namespaces(ns))
+        _css(selector.to_s, ns)
       end
 
       # First descendant matching +selector+, or nil. @return [Makiri::Node, nil]
       def at_css(selector, ns = nil)
-        _at_css(selector.to_s, _css_namespaces(ns))
+        _at_css(selector.to_s, ns)
       end
 
       # Whether this node matches +selector+ (full selector, combinators included).
       # @return [Boolean]
       def matches?(selector, ns = nil)
-        _css_matches(selector.to_s, _css_namespaces(ns))
+        _css_matches(selector.to_s, ns)
       end
 
       private
@@ -61,25 +64,6 @@ module Makiri
       def unprefixed_element_namespace
         nil
       end
-
-      # Build the {prefix => uri} hash the native primitives register. Matching
-      # Nokogiri: with NO explicit namespaces the document's own declarations are
-      # collected (the default namespace under the synthetic prefix "xmlns", so a
-      # bare type selector binds to it - the RSS/Atom common case); but once the
-      # caller passes a namespaces hash, ONLY those prefixes are used and a bare
-      # selector resolves to no namespace (Nokogiri disables the default binding
-      # the moment an explicit map is given). Reading only the root's
-      # declarations is O(root attributes), not the whole-document walk.
-      def _css_namespaces(user)
-        return user.transform_keys(&:to_s).transform_values(&:to_s) if user && !user.empty?
-
-        reg = {}
-        root = document&.root
-        root&.namespace_definitions&.each do |ns|
-          reg[ns.prefix.nil? ? "xmlns" : ns.prefix] = ns.href
-        end
-        reg
-      end
     end
   end
 end

data/lib/makiri.rb

@@ -2,17 +2,36 @@
 
 require_relative "makiri/version"
 
-# Native extension (a Rust crate). Located at lib/makiri/<ruby_abi>/makiri.{so,bundle}
-# (created by rake-compiler). Loading is gated so the gem can be required
-# in environments where the binary is not yet built (the require error
-# is then surfaced clearly).
-begin
-  RUBY_VERSION =~ /(\d+\.\d+)/
-  require_relative "makiri/#{Regexp.last_match(1)}/makiri"
-rescue LoadError
+# Native extension (a Rust crate): lib/makiri/<major.minor>/makiri.<dlext> in a
+# precompiled gem (one per Ruby), else lib/makiri/makiri.<dlext> (a source
+# install, or a checkout's `rake compile`). The versioned one is required only
+# if it is there: rescuing LoadError instead would also swallow the extension's
+# own refusal (a binary built for another Ruby raises LoadError from its init)
+# and load the fallback over it.
+versioned = "makiri/#{RUBY_VERSION[/\A\d+\.\d+/]}/makiri"
+if File.exist?(File.join(__dir__, "#{versioned}.#{RbConfig::CONFIG["DLEXT"]}"))
+  require_relative versioned
+else
   require_relative "makiri/makiri"
 end
 
+# The fallback loads lib/makiri/makiri.<dlext> whichever version of this gem's
+# Ruby code is asking: a checkout (or a Bundler `path:` gem) keeps one binary
+# from its last compile, and one from another gem version lacks or misnames
+# methods. The extension states what it was built as, and a mismatch stops
+# here; a binary older than the constant states nothing, a mismatch too. (A
+# binary for another Ruby never gets this far: the extension refuses it
+# before it defines anything.)
+module Makiri
+  native_version = const_defined?(:NATIVE_VERSION, false) ? NATIVE_VERSION : "(unknown)"
+  if native_version != VERSION
+    raise LoadError,
+          "makiri's native extension was built as makiri #{native_version}, but was " \
+          "loaded by makiri #{VERSION}; rebuild it (`bundle exec rake clean compile` in a " \
+          "checkout, or reinstall the gem)"
+  end
+end
+
 require_relative "makiri/error"
 require_relative "makiri/clone_via_dup"
 require_relative "makiri/xpath_syntax"