leptris 1.9.8 → 1.9.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f306f9bc45d304b82c3db1ac2936dcc0d708b21d2caf595e4a9484da5c6b48a
-  data.tar.gz: ce9b04f6f1e91e6dffd1ff68ce70967b8b2bcff8351132db2f3312e4b534e803
+  metadata.gz: 4e7dca7e58492747ba0b5843937a7a8a914afa52f4f7271e2b808d1b895a2ded
+  data.tar.gz: bf399063035b7cacd20893813e89f85582594ef7644ab8b2ef076772cc40c094
 SHA512:
-  metadata.gz: 40618f16214157768b018c774816f738a8cbce00e757286822a69f22f71413605c165448a22644b1ff5cc66a387ce63d6e2c496167b8049f2e80ab7cdf124582
-  data.tar.gz: f3c5d00e54f051510d76db44582806252ccf84091c9c9eb11915fc43675282721f4224fada0331f45616250be411362f981d545fb5de47bfcaadfaf09a4954bb
+  metadata.gz: df766bafa6dc7d590909f4f6d2a475446115b5d9cd1d57605558654959e699188f1a36329248c653b501e5e432a9a604533e01dd476e9b350a5510be27fa7ca3
+  data.tar.gz: c0c8f0f164ceadd0c24d476ca8c4948582e091379f7f976a0fdbfc073d482a97c8a80bf29ad6601f2ad474e0fd4464c5e903cb382b56350be2a6c07a1ef0ecf6

data/CHANGELOG.md

@@ -5,6 +5,47 @@ 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.10] - 2026-08-26
+
+### Changed
+
+- **README: Migrating from Nokogiri, caught up to the 1.9.x
+  surface** — the notable-differences list now covers the lifetime
+  contract (UseAfterFreeError on freed-document reads/mutations),
+  readonly mode, recover parsing + last_error_position, searchable
+  fragments, receiver-relative css, and expanded-name attribute
+  access, each with the migrating reader's context.
+- **Spec organization**: the eight-round perf_surface_spec grab-bag
+  splits into one file per concern (seam_and_reads,
+  sax_and_query_paths, lifetime_contract, fragment_and_position,
+  receiver_relative_css). Suite count unchanged at 274; each file
+  is one scannable context.
+
+## [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

data/README.adoc

@@ -177,7 +177,7 @@ against a readonly document is legal; mutating the frozen one is not.
 `#at_xpath(*exprs)` :: first match (or scalar), like `xpath(*exprs).first`.
 `#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]
@@ -410,7 +410,26 @@ Notable differences:
 * `Node#children` includes whitespace text nodes (same as Nokogiri); use
   `#element_children` or `#first_element_child` to skip them.
 * CSS support is intentionally minimal — for advanced selectors, drop to
-  `xpath`.
+  `xpath`. `css` is receiver-relative (Nokogiri semantics): scoped to
+  an element or fragment, document-wide from a Document.
+* `DocumentFragment` is searchable (`fragment.xpath/at_xpath/css/at_css/search`)
+  — Nokogiri fragment parity.
+* Expanded-name attribute access: `Element#attribute_ns(uri, local)` /
+  `#has_attribute_ns?(uri, local)` — XML Namespaces 1.0 semantics
+  (cross-prefix match, nil URI matches no-namespace, xmlns invisible).
+* `Leptris::XML.parse(xml, recover: true)` returns an empty document
+  with the failure recorded on the thread-global last error instead of
+  raising ParseError — libxml2 `XML_PARSE_RECOVER` semantics. The
+  companion `Document#last_error_position` returns `[line, column]`.
+* `Leptris::XML.parse(xml, readonly: true)` (or `Document#readonly!`)
+  freezes the document for reading: mutations raise ReadOnlyError, read
+  methods memoize aggressively. Faster steady state; no Nokogiri
+  equivalent.
+* **Lifetime contract**: a borrowed handle used after the owning
+  document has been freed (or GC'd) raises `Leptris::XML::UseAfterFreeError`.
+  Nokogiri is silent on this — migrating code that holds Node references
+  past Document disposal will see the error; silence-replace-UAF patterns
+  from Nokogiri do not apply.
 * No `Nokogiri::HTML` or `Nokogiri::CSS` parser. Leptris is XML-only.
 * No XSLT, no RelaxNG / DTD validation, no schema caching.
 * No built-in JRuby / TruffleRuby support — only CRuby via `ffi`.

data/Rakefile

@@ -55,9 +55,27 @@ task default: :spec
 namespace :audit do
   desc "Fail when ffi.rb attachments and library exports drift"
   task :symbols do
+    # nm cannot read MSVC PE export tables (every symbol reports as
+    # unexported -> guaranteed false drift), so Windows skips: the
+    # darwin/linux CI legs enforce the mirror — any one platform's
+    # build of the same C surface suffices.
+    if Gem.win_platform?
+      puts "audit:symbols: skipped on Windows (PE export tables); " \
+           "darwin/linux legs enforce the mirror"
+      next
+    end
+    # Probe nm without a shell: the multi-arg system() execs
+    # directly, so there is no which/redirect syntax to be
+    # platform-hostile. File::NULL is NUL where it must be; a
+    # missing binary is falsy either way (ENOENT rescue belts the
+    # older spawn behavior).
+    unless nm_available?
+      puts "audit:symbols: skipped (nm unavailable on this platform)"
+      next
+    end
     lib = Dir.glob("lib/libleptris.{dylib,so,dll}").first
-    unless lib && system("which nm > /dev/null 2>&1")
-      abort "audit:symbols: vendored library or nm not found — run rake compile"
+    unless lib
+      abort "audit:symbols: vendored library not found — run rake compile"
     end
     exported = `nm -gU #{lib}`
       .lines.map { |l| l.split[2] }.compact
@@ -82,6 +100,13 @@ namespace :audit do
       abort "audit:symbols: drift detected"
     end
   end
+
+  # @api private
+  def nm_available?
+    system("nm", "--version", out: File::NULL, err: File::NULL)
+  rescue Errno::ENOENT
+    false
+  end
 end
 
 require "rubygems/package_task"

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.8"
+  VERSION = "1.9.10"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.8
+  version: 1.9.10
 platform: ruby
 authors:
 - Ribose Inc.
@@ -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