leptris 1.9.7 → 1.9.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '001396e9d1eca04e38bc3223964f4d8b8aa22f7672d32d6dc936f4730db35c60'
-  data.tar.gz: a4a24591d60276ea69fc9be41cd1b30aa6ac66df1cb77aa9f258489f2a8e7f28
+  metadata.gz: b2e2451251a0c5aec3567f67ed11c48f1b48d1a9f3622bc8c3fe62f03192c185
+  data.tar.gz: 6be47e0deac36287f736e5b6b7b9755ce4b1e2e4e3986959caa750c5072bcada
 SHA512:
-  metadata.gz: 94b3e177f5419851483df347346993d6e42b9eb7a2ed7cca238804547cd65ab81ef7cdd3de04fe9898493f35e13178b359b99aecf653aea379a5714be088fc87
-  data.tar.gz: d30f779432c68c767754e55d2695e53c920e94d3f37b31603a76841c4c462b4afd62f192ba02de647ba762b4c4be59748615803fbdaedd570dd69c3ab5a488bd
+  metadata.gz: a352efddd7e68f48e17d7126bf1d003d8da0c2eb5cdf09be1c7c7d42b739a761208792e4b45033cd7dfd928123ff7db80c8d629a0f625554d778c7c6b822e4df
+  data.tar.gz: 71c3504e8592fab25b026c68d25300c2420c22e932546257dd6d5cc819c47b9cf3ff82cbd80136d55e8250efe1c6b835a82d336b341d3cdbbcde8177ff16933d

data/CHANGELOG.md

@@ -5,6 +5,49 @@ All notable changes to Leptris will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.9] - 2026-08-26
+
+### Changed
+
+- **CI gates the symbol audit**: the build workflow runs
+  `rake compile audit:symbols` before the suite — upstream surface
+  drift now fails CI on the PR that first sees it instead of
+  relying on someone remembering to run it. The task skips
+  gracefully where nm is unavailable (Windows).
+- **benchmark/leptris_vs_nokogiri.rb prints live provenance**
+  (library, gem, nokogiri, ruby versions) instead of a frozen
+  footer claiming "v0.12.0 / 176 specs".
+- README: the `#search` dispatch description now matches the
+  heuristic the code implements (path-prefix → xpath; everything
+  else translates as CSS, commas included).
+
+### Meta
+
+- **ADR 0006** records the ruby-variant packaging policy as
+  practiced since 1.9.0: the `ruby` platform gem ships as the
+  fallback/source variant without a vendored library, safe under
+  the eager-load failure mode (issue #49) — clarifying the 1.9.0
+  changelog's "platform variants only" phrasing without rewriting
+  history.
+
+## [1.9.8] - 2026-08-26
+
+### Added
+
+- **`rake audit:symbols`**: the lockstep drift detector as an
+  executable step — `nm -gU` on the vendored library vs the ffi.rb
+  attach list, failing with both directions of drift (ADR 0001's
+  enforcement arm; previously prose plus ad-hoc pipelines).
+
+### Changed
+
+- ffi.rb attaches the five header-declared exports past cleanups
+  had dropped (element_children, serialize_document,
+  xpath_ns_set_add, xpath_result_get, xpath_result_get_nodes) —
+  mirror-only, supersession noted inline. The audit now runs green:
+  **224/224 symbols in lockstep**. Pull-attribute batch fetch asked
+  upstream (leptris/leptris#562).
+
 ## [1.9.7] - 2026-08-26
 
 ### Added

data/CLAUDE.md

@@ -91,6 +91,7 @@ lib/leptris/xml/css_to_xpath.rb   — minimal CSS translation
   check both before proposing refactors; they exist so reviews
   stop re-deriving settled questions.
 - libleptris public headers (`src/include/leptris/*.h`) are the
-  contract; when symbols change, bump lockstep and audit
-  attached-vs-exported (`nm -gU` on a fresh build).
+  contract; when symbols change, bump lockstep and run
+  `rake audit:symbols` (attached == exported on the vendored
+  library; fails listing both directions of drift).
 - Upstream issues worth tracking live at leptris/leptris.

data/README.adoc

@@ -169,14 +169,15 @@ against a readonly document is legal; mutating the frozen one is not.
 
 == Searching: XPath and CSS
 
-`Document` and `Element` (via `Leptris::XML::Searchable`) support:
+`Document`, `Element`, and `DocumentFragment` (via
+`Leptris::XML::Searchable`) support:
 
 [horizontal]
 `#xpath(*exprs)` :: evaluate XPath; returns `NodeSet`, `true`/`false`, `Float`, or `String` depending on the expression.
 `#at_xpath(*exprs)` :: first match (or scalar), like `xpath(*exprs).first`.
-`#css(*selectors)` :: minimal CSS-to-XPath translation, then `xpath`.
+`#css(*selectors)` :: minimal CSS-to-XPath translation, then `xpath`. Receiver-relative (Nokogiri semantics): scoped to the element or fragment, document-wide from a Document.
 `#at_css(*selectors)` :: first match of `css`.
-`#search(*exprs)` :: dispatches on syntax — `/`-prefixed or `,`-separated → `xpath`, otherwise `css`.
+`#search(*exprs)` :: dispatches on syntax — path-prefixed expressions (`/`, `.`, `..`) go to `xpath`; everything else translates as CSS (comma unions included).
 `#at(*exprs)` :: first match of `search`.
 
 [source,ruby]
@@ -190,6 +191,11 @@ doc.at_xpath("string(//book[1]/@id)")     # => "b1"
 doc.css("book[lang='en'] title")          # => NodeSet[<title>Refactoring</title>]
 doc.at_css("book#b1 title")               # => <title>Refactoring</title>  (id selector)
 doc.css("book:first-child")               # first <book>
+
+# css is receiver-relative: scoped to the receiver, not the document
+doc.root.at_css("book").css("title")      # titles under THAT book only
+frag = doc.fragment("<a x='1'><n/></a>")
+frag.css("a > n")                         # searches the fragment
 ----
 
 XPath result type follows XPath 1.0 semantics:

data/Rakefile

@@ -49,6 +49,45 @@ task spec: :compile unless ENV.key?("LEPTRIS_LIB_PATH")
 
 task default: :spec
 
+# Lockstep drift detector (ADR 0001): ffi.rb mirrors the public
+# header, so attached == exported must hold on the vendored library.
+# Run after `rake compile` and before any lockstep release.
+namespace :audit do
+  desc "Fail when ffi.rb attachments and library exports drift"
+  task :symbols do
+    lib = Dir.glob("lib/libleptris.{dylib,so,dll}").first
+    unless system("which nm > /dev/null 2>&1")
+      puts "audit:symbols: skipped (nm unavailable on this platform)"
+      next
+    end
+    unless lib
+      abort "audit:symbols: vendored library not found — run rake compile"
+    end
+    exported = `nm -gU #{lib}`
+      .lines.map { |l| l.split[2] }.compact
+      .map { |n| n.sub(/\A_/, "") }
+      .select { |n| n.start_with?("leptris_") }
+      .map { |n| n.sub(/\Aleptris_/, "") }.sort
+    attached = File.read("lib/leptris/xml/ffi.rb")
+      .scan(/attach_function :leptris_([a-z_0-9]+)/).flatten.sort
+    unattached = exported - attached
+    unexported = attached - exported
+    unless unattached.empty?
+      puts "exported but NOT attached (upstream surface drift):"
+      unattached.each { |s| puts "  leptris_#{s}" }
+    end
+    unless unexported.empty?
+      puts "attached but NOT exported (stale attachment):"
+      unexported.each { |s| puts "  leptris_#{s}" }
+    end
+    if unattached.empty? && unexported.empty?
+      puts "audit:symbols: #{attached.length}/#{exported.length} symbols in lockstep"
+    else
+      abort "audit:symbols: drift detected"
+    end
+  end
+end
+
 require "rubygems/package_task"
 
 desc "Build the pure-Ruby gem"

data/docs/adr/0006-ruby-variant-policy.md

@@ -0,0 +1,25 @@
+# ADR 0006: the ruby-platform variant ships as the fallback, unvendored
+
+## Context
+The 1.9.0-era CHANGELOG said "never publishes ruby-platform releases
+without the vendored library — platform variants only", and an early
+fix removed the `gem:native:any` task. The 1.9.0 lockstep restored
+the `ruby` matrix entry deliberately, and every release since has
+published the variant — practice contradicting the recorded policy.
+
+## Decision
+The `ruby`-platform gem ships as the fallback/source variant WITHOUT
+a vendored library, by design. It is safe because library resolution
+is eager (issue #49): on a machine without a usable libleptris the
+gem fails at `require` with the actionable remedy (install the
+platform-specific variant or set LEPTRIS_LIB_PATH) instead of deep
+inside Document.parse. Bundler prefers platform-specific gems
+wherever they exist (9 of 10 published variants are precompiled);
+the ruby variant serves source installs and exotic platforms that
+accept providing their own library.
+
+## Consequences
+Do not re-propose removing the `platform: any` release leg without
+new evidence that bundler misresolves it in practice. A future
+change to the eager-load behavior (ADR 0005 ordering aside) must
+keep the ruby variant failing loudly at require time.

data/lib/leptris/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Leptris
-  VERSION = "1.9.7"
+  VERSION = "1.9.9"
 end

data/lib/leptris/xml/ffi.rb

@@ -173,6 +173,10 @@ module Leptris
       # count-only query returning the TOTAL across every child kind.
       attach_function :leptris_node_children,
         [:leptris_node_ref, :pointer, :size_t], :size_t
+      # Element-only batch; mirror-only — fetch_children rides the
+      # all-kind node_children above.
+      attach_function :leptris_element_children,
+        [:leptris_element, :pointer, :size_t], :size_t
       attach_function :leptris_node_as_element,
         [:leptris_node_ref], :leptris_element
       attach_function :leptris_element_as_node,
@@ -402,6 +406,12 @@ module Leptris
       # which (element / synthetic attribute / text / other).
       attach_function :leptris_xpath_result_node_kind,
         [:leptris_xpath_result, :size_t], :int
+      # Pre-_ex variants, superseded by xpath_result_get_nodes_ex /
+      # xpath_result_get_node; mirror-only (ADR 0001).
+      attach_function :leptris_xpath_result_get,
+        [:leptris_xpath_result, :size_t], :leptris_element
+      attach_function :leptris_xpath_result_get_nodes,
+        [:leptris_xpath_result, :pointer, :size_t], :size_t
       attach_function :leptris_xpath_result_get_node,
         [:leptris_xpath_result, :size_t], :leptris_node_ref
       attach_function :leptris_xpath_result_node_name,
@@ -447,6 +457,10 @@ module Leptris
         [:leptris_xpath_ns_set], :void
       # One-call constructor: flat array of 2*pair_count alternating
       # prefix/URI strings.
+      # Per-pair add; superseded by ns_set_new_from_pairs (one call);
+      # mirror-only (ADR 0001).
+      attach_function :leptris_xpath_ns_set_add,
+        [:leptris_xpath_ns_set, :string, :string], :leptris_status
       attach_function :leptris_xpath_ns_set_new_from_pairs,
         [:pointer, :size_t], :leptris_xpath_ns_set
       attach_function :leptris_xpath_eval_ns,
@@ -507,6 +521,10 @@ module Leptris
 
       attach_function :leptris_document_serialize,
         [:leptris_document, :pointer], :pointer
+      # Deprecated automatic-options alias (header: prefer
+      # leptris_document_serialize); mirror-only.
+      attach_function :leptris_serialize_document,
+        [:leptris_document], :pointer
       # libleptris >= 1.9.0: caller-buffer serialization with options
       # (leptris#541). buf=NULL is a size query; the size-query +
       # fill pair reuses one serialization through a per-document

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.7
+  version: 1.9.9
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-25 00:00:00.000000000 Z
+date: 2026-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -74,6 +74,7 @@ files:
 - docs/adr/0003-readonly-memoization-pattern.md
 - docs/adr/0004-lifetime-guard.md
 - docs/adr/0005-autoload-manifest-ordering.md
+- docs/adr/0006-ruby-variant-policy.md
 - leptris.gemspec
 - lib/leptris.rb
 - lib/leptris/version.rb