makiri 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 383a2feea9ae25aca8e66985862eb3dfbbb64682771fc4578d9f0f6c11100d43
-  data.tar.gz: 774f2089e9b581b757cf0e142e937f892a87ccd71bb7c60f74666d9007bcac5c
+  metadata.gz: 80c74b7d335f5f5f93f8476a8f99a8918560df8cf75f43a5a71d9b132e892873
+  data.tar.gz: d6593459917f22ceb301093d17b981a597d8be7d975d1fab1e4142f6cf17fcbc
 SHA512:
-  metadata.gz: 575cdf673cf1c0f2f76bc641c978a5c946e99a19ebc9bd92d761aa23ac9e7d9a72d980120c22b7bc344a95d0236bcfff6887fc09e28836f64739ca87a18c7e8d
-  data.tar.gz: 8b5f74af6c317ce0928c2b700d4061828621c4115685b80c3b49c47bf65f521f46431e4cf22ce064eadf0c30dc2f68611f84b3e4e4ead2b162ef5369c5544b7a
+  metadata.gz: efa98c3ca322d6a3ee141428c1f5e9c3e5b46fba9dde4d7ac75d7dcfdf27d4dd083ef46eed5fb8db21685396d86caeb58e1755f9dd5014d396674cc149378df9
+  data.tar.gz: 836d97359577dfcd4bd60a8de0dfcf355c596b95fa7fffd5e56a0a355bb4267f3141bf8786f4f905596d79bef44721eeb3bfe4f25fa97e489c5aa3319c9f7655

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [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/ext/makiri/rust/build.rs

@@ -41,6 +41,10 @@ fn main() {
     println!("cargo:rerun-if-changed=build.rs");
     println!("cargo:rerun-if-env-changed=MAKIRI_LEXBOR_INCLUDE");
 
+    if std::env::var_os("CARGO_FEATURE_RUBY").is_some() {
+        gem_version();
+    }
+
     // Only a build that reads Lexbor's layout pays for this. Kani builds with
     // `--no-default-features` and has no Lexbor headers to point at, which is
     // the whole reason `rake kani` needs no `rake compile` first.
@@ -472,3 +476,36 @@ fn definition(text: &str, name: &str) -> Option<(String, String)> {
     }
     None
 }
+
+/// Embed the gem's version (`lib/makiri/version.rb`, the one place it is
+/// written) as `MAKIRI_GEM_VERSION`, which `init` publishes as
+/// `Makiri::NATIVE_VERSION` for `lib/makiri.rb` to check the loaded binary
+/// against. Read from the source rather than passed in by extconf, so every
+/// cargo build of the extension carries it and none can carry a stale one.
+fn gem_version() {
+    let manifest = std::path::PathBuf::from(std::env::var("CARGO_MANIFEST_DIR").unwrap());
+    let path = manifest.join("../../../lib/makiri/version.rb");
+    println!("cargo:rerun-if-changed={}", path.display());
+    let source = std::fs::read_to_string(&path)
+        .unwrap_or_else(|e| panic!("cannot read {}: {e}", path.display()));
+    /* `VERSION = "x"` or `VERSION = 'x'`, a trailing `.freeze` or comment
+     * allowed: the literal is what is between the first quote and its match. */
+    let version = source
+        .lines()
+        .find_map(|line| {
+            let rest = line.trim().strip_prefix("VERSION")?.trim_start();
+            let rest = rest.strip_prefix('=')?.trim_start();
+            let quote = rest.chars().next().filter(|c| *c == '"' || *c == '\'')?;
+            let body = &rest[1..];
+            body.find(quote).map(|end| &body[..end])
+        })
+        .filter(|v| !v.is_empty())
+        .unwrap_or_else(|| {
+            panic!(
+                "build.rs reads the gem version from a `VERSION = \"x.y.z\"` line in {}, \
+                 and found none",
+                path.display()
+            )
+        });
+    println!("cargo:rustc-env=MAKIRI_GEM_VERSION={version}");
+}

data/ext/makiri/rust/src/bridge/html.rs

@@ -17,12 +17,14 @@ use crate::init::{
     CLASS_HTML_PROCESSING_INSTRUCTION, CLASS_HTML_TEXT, CLASS_XML_DOCUMENT,
 };
 use crate::lexbor::adapter::html::{
-    ForeignNode, HtmlNode, HtmlNodeKey, HtmlNodeMut, Insertion, NodeType, Place, RawDoc, RawNode,
+    ForeignNode, HtmlNode, HtmlNodeKey, HtmlNodeMut, HtmlTree, Insertion, NodeType, Place, RawDoc,
+    RawNode,
 };
 use crate::lexbor::fragment::import_with_fixup;
 
 use crate::bridge::string::{RubyData, RubyText};
 use crate::bridge::wrapper::*;
+use crate::child_index::{ChildList, Children, TokenTree};
 use crate::lexbor::adapter::html::{HtmlDoc, HtmlElementMut};
 use crate::lexbor::adapter::AdapterOom;
 
@@ -241,6 +243,50 @@ pub fn wrap_node(node: Option<HtmlNode<'_>>, document: Value) -> Result<Option<V
         .transpose()
 }
 
+/* ------------------------------------------------------------------ *
+ * indexing a child list                                               *
+ * ------------------------------------------------------------------ */
+
+/// The Lexbor tree for [`crate::child_index`]: a node's pointer is its token.
+/// The links are [`HtmlTree`]'s, the raw ones `#children` follows, so the two
+/// agree - a `<template>`'s own (empty) child list included.
+impl<'d> TokenTree for HtmlTree<'d> {
+    fn token(&self, n: HtmlNode<'d>) -> usize {
+        RawNode::from(n).as_ptr() as usize
+    }
+    fn node_of(&self, token: usize) -> Option<HtmlNode<'d>> {
+        let raw = RawNode::from_ptr(token as *mut core::ffi::c_void)?;
+        // SAFETY: `child_index` asks only for a token it recorded for a list
+        // of this document, so by `ChildPositionMemo`'s invariant it names a
+        // node that is still a child there - in the document the receiver
+        // keeps alive for `'d`. Lexbor detaches rather than frees, so it was
+        // never released.
+        Some(unsafe { raw.as_node() })
+    }
+}
+
+/// The tree every HTML receiver lends its child lists, as `&'static`: a
+/// `const` item is what may be borrowed for that long (the type holds
+/// nothing).
+const HTML_TREE: HtmlTree<'static> = HtmlTree::new();
+
+impl ChildListHost for HtmlSelf {
+    type Tree<'a> = HtmlTree<'a>;
+    fn document(&self) -> Value {
+        self.document
+    }
+    fn children(&self, list: ChildList) -> Children<'_, HtmlTree<'_>> {
+        Children {
+            tree: &HTML_TREE,
+            parent: self.node(),
+            list,
+        }
+    }
+    fn wrap_child(&self, n: Option<HtmlNode<'_>>) -> Result<Option<Value>, Error> {
+        wrap_node(n, self.document)
+    }
+}
+
 /* ------------------------------------------------------------------ *
  * resolving a long-lived key                                          *
  * ------------------------------------------------------------------ */

data/ext/makiri/rust/src/bridge/ruby.rs

@@ -20,6 +20,47 @@ pub use rb_sys::{ID, VALUE};
 
 /* The two conveniences every bridge and glue module shares. */
 
+/// The `MAJOR.MINOR` of the Ruby whose headers this extension was compiled
+/// against - its ABI, since a teeny release keeps it. Published as
+/// `Makiri::NATIVE_RUBY_API_VERSION`.
+pub fn ruby_api_version() -> String {
+    format!(
+        "{}.{}",
+        rb_sys::RUBY_API_VERSION_MAJOR,
+        rb_sys::RUBY_API_VERSION_MINOR
+    )
+}
+
+/// `Err(LoadError)` when the running Ruby's API `MAJOR.MINOR` is not the one
+/// this extension was compiled for.
+///
+/// The FIRST thing `Init_makiri` does. A release Ruby does not check
+/// `ruby_abi_version` itself, and under macOS's `-undefined dynamic_lookup`
+/// a binary built for another Ruby loads and then misreads the interpreter's
+/// structs - defining one class could already corrupt it, so the check
+/// cannot wait for `lib/makiri.rb`. It reads the running Ruby's exported
+/// `ruby_api_version` (three ints, whose layout no Ruby changes) and nothing
+/// else; only a mismatch goes on to build the exception.
+pub fn check_running_ruby_api(ruby: &Ruby) -> Result<(), Error> {
+    // SAFETY: an immutable `const int[3]` libruby exports, read by value.
+    let running = unsafe { (rb_sys::ruby_api_version[0], rb_sys::ruby_api_version[1]) };
+    let built = (
+        rb_sys::RUBY_API_VERSION_MAJOR as core::ffi::c_int,
+        rb_sys::RUBY_API_VERSION_MINOR as core::ffi::c_int,
+    );
+    if running == built {
+        return Ok(());
+    }
+    Err(Error::new(
+        ruby.exception_load_error(),
+        format!(
+            "makiri's native extension was built for Ruby {}.{}, but this is Ruby {}.{}; \
+             rebuild it (`bundle exec rake clean compile` in a checkout, or reinstall the gem)",
+            built.0, built.1, running.0, running.1
+        ),
+    ))
+}
+
 /// `Makiri::Error` - the one definition; the modules that each kept a private
 /// copy of this now import it.
 pub fn error_class() -> magnus::ExceptionClass {

data/ext/makiri/rust/src/bridge/string.rs

@@ -411,6 +411,30 @@ pub unsafe fn ruby_str_from_utf8(bytes: &[u8]) -> VALUE {
     rb_sys::rb_utf8_str_new(bytes.as_ptr() as *const c_char, bytes.len() as c_long)
 }
 
+/// A DOM name as a Ruby String: frozen and deduplicated, tagged UTF-8 -
+/// Ruby's own `-"div"`, so every read of one name answers the same object and
+/// allocates nothing once Ruby has it.
+///
+/// THE contract for the name readers of both representations: `local_name`,
+/// `prefix`, `namespace_uri` and `tag_name` answer through this, and only
+/// `#name` (Nokogiri's, which callers may edit) answers a fresh String.
+/// Character data - text, attribute values - is never interned.
+///
+/// Safe to call with any bytes: `rb_enc_interned_str` copies them, and bytes
+/// that were not UTF-8 would make a wrong String, never a memory error. Every
+/// caller passes a document's name, which is UTF-8 by the text-input contract.
+pub fn dom_name_str(bytes: &[u8]) -> Value {
+    // SAFETY: a slice's pointer and length, read for the call; the encoding
+    // is Ruby's static UTF-8 one. The result is a live String.
+    unsafe {
+        crate::bridge::ruby::value(rb_sys::rb_enc_interned_str(
+            bytes.as_ptr() as *const c_char,
+            bytes.len() as c_long,
+            rb_sys::rb_utf8_encoding(),
+        ))
+    }
+}
+
 /* ---- the strict text contract ---- */
 
 /// Check `bytes` against the strict contract, returning the specific

data/ext/makiri/rust/src/bridge/wrapper.rs

@@ -18,6 +18,8 @@ use magnus::{Error, Value};
 
 use crate::bridge::ruby::{value, VALUE};
 use crate::bridge::typed::{Hooks, Marker, Relocator, TypedType};
+use crate::child_index::{ChildList, ChildPositionMemo, Children, TokenTree};
+use crate::dom_rules::Tree;
 use crate::falloc::{MapInsert, Reserve};
 use crate::init::{RbConst, CLASS_DOCUMENT};
 use crate::lexbor::adapter::html::{HtmlDoc, HtmlNodeKey, RawDoc, RawNode};
@@ -387,6 +389,9 @@ pub struct DocData {
     /// Boxed and optional so a document nobody navigates never allocates a
     /// cache, and its wrapper stays one pointer wide.
     nodes: Option<Box<NodeCache>>,
+    /// Where `child_count` / `child_at` last were ([`ChildPositionMemo`]).
+    /// Allocates nothing until the first of them records.
+    child_memo: ChildPositionMemo,
 }
 
 impl DocData {
@@ -482,6 +487,7 @@ impl Hooks for DocData {
         core::mem::size_of::<DocData>()
             .saturating_add(self.external_bytes())
             .saturating_add(self.nodes.as_ref().map_or(0, |c| c.memsize()))
+            .saturating_add(self.child_memo.memsize())
     }
 }
 
@@ -642,6 +648,7 @@ impl DocumentShell {
                     errors: QFALSE,
                     report: ExternalReport::default(),
                     nodes: None,
+                    child_memo: ChildPositionMemo::default(),
                 },
                 |d| d.errors = errors.as_raw(),
             )
@@ -1028,6 +1035,52 @@ pub fn attribute_version(rb_doc: Value) -> Result<u64, Error> {
     Ok(DOC_TYPE.get(&rb_doc)?.edits.attribute_version)
 }
 
+/* ---- the child-position memo ---- */
+
+/// Run `f` over the document's [`ChildPositionMemo`] and its current
+/// `tree_version`, which every use of the memo must pass it - the memo keeps
+/// its own invariant from that (`crate::child_index`).
+///
+/// `f` runs inside the document's borrow, so it must not run Ruby; a walk of
+/// the child links does not.
+fn with_child_memo<R>(rb_doc: Value, f: impl FnOnce(&mut ChildPositionMemo, u64) -> R) -> R {
+    with_doc_data_known(rb_doc, |d| f(&mut d.child_memo, d.edits.tree_version))
+}
+
+/// A receiver whose child lists `#child_count` / `#child_at` and their
+/// element twins read - an HTML or XML node or Document. A representation
+/// says which tree and node it is and how a child is wrapped; counting and
+/// indexing are written once, here, and the four Ruby methods once, over
+/// this, in `glue::node`.
+pub trait ChildListHost: magnus::TryConvert {
+    type Tree<'a>: TokenTree
+    where
+        Self: 'a;
+
+    /// The Document whose memo the lists use.
+    fn document(&self) -> Value;
+    /// The receiver's `list`.
+    fn children(&self, list: ChildList) -> Children<'_, Self::Tree<'_>>;
+    /// A child of the receiver as its Ruby wrapper; None is nil.
+    fn wrap_child(&self, n: Option<<Self::Tree<'_> as Tree>::Node>)
+        -> Result<Option<Value>, Error>;
+
+    /// How many children are in `list`.
+    fn child_count(&self, list: ChildList) -> usize {
+        with_child_memo(self.document(), |memo, version| {
+            self.children(list).count(memo, version)
+        })
+    }
+
+    /// The wrapped child at `index` in `list`, or nil past the end.
+    fn child_at(&self, list: ChildList, index: usize) -> Result<Option<Value>, Error> {
+        let found = with_child_memo(self.document(), |memo, version| {
+            self.children(list).at(memo, version, index)
+        });
+        self.wrap_child(found)
+    }
+}
+
 /* ---- the document's mutation gate ---- */
 
 /// `Err(Makiri::Error)` while an evaluation with a handler is reading `rb_doc`.

data/ext/makiri/rust/src/bridge/xml.rs

@@ -29,6 +29,7 @@ use crate::bridge::wrapper::{
     ensure_document_mutable, node_repr, DocKind, DocumentShell, NodeRepr,
 };
 use crate::bridge::xml_decode::xml_decode_input_value;
+use crate::child_index::{ChildList, Children, TokenTree};
 use crate::init::{CLASS_NODE, CLASS_XML_DOCUMENT, EXC_XML_LIMIT_EXCEEDED, EXC_XML_SYNTAX_ERROR};
 use crate::init::{
     CLASS_XML_ATTR, CLASS_XML_CDATA_SECTION, CLASS_XML_COMMENT, CLASS_XML_DOCUMENT_FRAGMENT,
@@ -86,6 +87,35 @@ impl crate::bridge::wrapper::NodeHandleSource for NodeId {
     }
 }
 
+/// The arena for [`crate::child_index`]: a node's token is its `NodeId`'s,
+/// which the arena never reuses. The links are the arena's `Tree` ones,
+/// which `#children` follows (attributes are not on them).
+impl TokenTree for XmlDoc {
+    fn token(&self, n: NodeId) -> usize {
+        n.to_token()
+    }
+    fn node_of(&self, token: usize) -> Option<NodeId> {
+        NodeId::from_token(token)
+    }
+}
+
+impl ChildListHost for XmlSelf {
+    type Tree<'a> = XmlDoc;
+    fn document(&self) -> Value {
+        self.document
+    }
+    fn children(&self, list: ChildList) -> Children<'_, XmlDoc> {
+        Children {
+            tree: self.doc_ref(),
+            parent: self.id,
+            list,
+        }
+    }
+    fn wrap_child(&self, n: Option<NodeId>) -> Result<Option<Value>, Error> {
+        n.map(|id| wrap_xml_node(id, self.document)).transpose()
+    }
+}
+
 /// The arena node behind a wrapper.
 ///
 /// An XML Document resolves to its arena's DOCUMENT node. Anything else goes