leptris 1.9.6 → 1.9.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68bba6b5b68f0266571ec17a5809ea42ce7b1f37f0ba3577f9a06afd57db578f
-  data.tar.gz: d15442dd463ba2b4d09c6415e51c478c385c851eb6630ffc8c4d00e6a9ad7a57
+  metadata.gz: '001396e9d1eca04e38bc3223964f4d8b8aa22f7672d32d6dc936f4730db35c60'
+  data.tar.gz: a4a24591d60276ea69fc9be41cd1b30aa6ac66df1cb77aa9f258489f2a8e7f28
 SHA512:
-  metadata.gz: 52a5f4a5307b9b219911a9ebb7050672be1ad27096266e1c0732eb98ab40779055dcf25e4dd31c0ef0813966539e43894c6d4cdce20bd79e778a7df043c5631a
-  data.tar.gz: cd2e0732f88060f6ff02e3496bedca3d986fde26c9400c91efe458c05e96379caeddd50a5950eb65b965be23487aac243ada697855ade71d0ed6017bcfe49433
+  metadata.gz: 94b3e177f5419851483df347346993d6e42b9eb7a2ed7cca238804547cd65ab81ef7cdd3de04fe9898493f35e13178b359b99aecf653aea379a5714be088fc87
+  data.tar.gz: d30f779432c68c767754e55d2695e53c920e94d3f37b31603a76841c4c462b4afd62f192ba02de647ba762b4c4be59748615803fbdaedd570dd69c3ab5a488bd

data/CHANGELOG.md

@@ -5,6 +5,38 @@ 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.7] - 2026-08-26
+
+### Added
+
+- **DocumentFragment is searchable**: `fragment.xpath/at_xpath/
+  css/at_css/search` — Nokogiri fragment parity. The engine already
+  accepted the fragment handle as an XPath context node; the Ruby
+  class now includes Searchable.
+- **`Document#last_error_position`** → `[line, column]` (1-based,
+  thread-global and sticky per the C contract) — the position
+  companion to the recover mode's failure detail. Closes an
+  export-audit gap: `leptris_last_error_position` was exported but
+  unattached.
+
+### Changed
+
+- **css is receiver-relative** (Nokogiri semantics): `element.css`
+  and `fragment.css` scope to the receiver (`.//`), `Document#css`
+  stays document-absolute (`//`). Previously every receiver
+  translated to document-absolute XPath — wrong results for any
+  non-root element or fragment context. Document-context behavior
+  is unchanged.
+
+### Meta
+
+- **CONTEXT.md + docs/adr/**: the domain glossary (ownership model,
+  borrowed handles, wrapper identity, readonly contract, the seam
+  and its two faces) and five ADRs recording the settled decisions
+  (lockstep mirror, UTF-8 at the seam, hand-rolled memoization
+  pattern, the lifetime guard and its measured price, autoload
+  ordering) — future reviews stop re-deriving them.
+
 ## [1.9.6] - 2026-08-26
 
 ### Changed

data/CLAUDE.md

@@ -87,6 +87,9 @@ lib/leptris/xml/css_to_xpath.rb   — minimal CSS translation
 
 ## Reference
 
+- Domain vocabulary: CONTEXT.md. Settled decisions: docs/adr/ —
+  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).

data/CONTEXT.md

@@ -0,0 +1,39 @@
+# Domain glossary
+
+The vocabulary for talking about leptris-ruby. Architecture reviews
+use these names; see docs/adr/ for settled decisions.
+
+**The DOM** — the C tree built by libleptris. Single source of
+truth: every Ruby object is a view over it, and one Ruby method is
+one FFI call wherever possible.
+
+**The seam** — `Leptris::XML::FFI`: every attach, every struct
+layout, every buffer protocol, and the encoding policy (UTF-8 on
+both faces: returns and callback params). ABI knowledge appears
+nowhere else (document.rb's finalizer is ownership machinery;
+CStringArray is the char** adapter).
+
+**Ownership / the borrowed handle** — Document owns C memory
+(explicit `#free` or GC finalizer); every other object (Node,
+Element, Text, Comment, CDATA, PI, Attr, DocumentFragment, DocType)
+is a handle borrowed for its document's lifetime. Mutations raise
+ReadOnlyError on readonly documents; use of a handle after `#free`
+raises UseAfterFreeError.
+
+**Wrapper identity** — `Node.wrap` is the only wrapper constructor;
+the per-document strong cache makes the same C node always yield the
+same Ruby object (`doc.root.equal?(doc.root)`).
+
+**The readonly contract** — `readonly: true` makes reads memoizable
+because they cannot go stale; every read method follows the same
+three-line pattern (return memo → compute → store memo). Mutations
+are refused; detached factories still work.
+
+**Lockstep** — the gem's major.minor tracks libleptris; a C release
+is one PR (version.rb + Rakefile pin + CHANGELOG) then the release
+workflow; ffi.rb mirrors the public header so the attached-vs-
+exported audit (`nm -gU`) catches drift.
+
+**The recover mode** — `recover: true` parses return an empty
+document with the failure recorded on the thread-global last error
+(+ position), instead of raising ParseError.

data/docs/adr/0001-lockstep-mirror.md

@@ -0,0 +1,17 @@
+# ADR 0001: ffi.rb mirrors the public header
+
+## Context
+ffi.rb attaches ~30 functions the binding never calls (typed
+attribute accessors, copy-inserts, allocator hooks, xinclude
+getters). Reviews keep proposing to strip them.
+
+## Decision
+Keep attaching every public-header symbol. The mirror makes the
+attached-vs-exported audit (`nm -gU` on a fresh build) a drift
+detector: when libleptris changes its surface, the audit fails
+loudly instead of the binding silently missing ABI.
+
+## Consequences
+Attachment is declarative and cheap; unused functions cost nothing.
+When a call site starts using a string-returning mirror function,
+add it to the UTF8_RETURNS wrap-list (ADR 0002).

data/docs/adr/0002-utf8-at-the-seam.md

@@ -0,0 +1,19 @@
+# ADR 0002: UTF-8 at the seam, both faces
+
+## Context
+The headers contract every C string as UTF-8, but FFI's implicit
+string conversion returns ASCII-8BIT — on returns (2026-08-25,
+release 1.9.3) and on FFI::Function callback params (2026-08-25,
+1.9.4; only `characters` was corrected before).
+
+## Decision
+The encoding policy lives entirely in ffi.rb: the UTF8_RETURNS
+wrap-list for called string-returning attaches, plus
+read_owned_string, CStringArray.to_ruby, and the SAX adapter's
+nil-safe utf8 for callback params. Mirror-only attachments stay
+raw; they join the list when a call site appears.
+
+## Consequences
+Memoized readonly results can safely cache strings (they freeze as
+UTF-8, the correct encoding, not BINARY). Non-ASCII content can no
+longer leak BINARY into consumer code.

data/docs/adr/0003-readonly-memoization-pattern.md

@@ -0,0 +1,18 @@
+# ADR 0003: readonly memoization stays hand-rolled
+
+## Context
+Every readonly-mode read repeats the same three lines:
+`return @x if readonly_cached?(:@x); v = compute; @x = v if
+@document&.readonly?`. ~25 sites. Reviews keep proposing a
+`readonly_memo(ivar) { }` concentrator.
+
+## Decision
+Keep the pattern hand-rolled. Concentrating it requires
+instance_variable_get/set — banned project-wide (encapsulation:
+no reaching into another object's ivars, and metaprogrammed ivar
+access hides the memo identity from readers).
+
+## Consequences
+The repetition IS the invariant — greppable, one file at a time.
+New readonly reads copy the three lines verbatim; a site that
+deviates is visible in review.

data/docs/adr/0004-lifetime-guard.md

@@ -0,0 +1,21 @@
+# ADR 0004: borrowed handles validate their lender
+
+## Context
+Before 1.9.5, only Document's own methods checked freed state:
+`doc.free; node.name` read freed memory silently (verified
+returning ""), stale mutations risked segfaults.
+
+## Decision
+`Node#ensure_alive!` guards every c_ptr-derefercing entry point —
+after memo checks (memoized readonly results stay check-free) and
+folded into `ensure_writable!` for mutations. The check is the
+cheapest sufficient one: `Document#c_ptr.nil?` (#free nils it; the
+GC finalizer cannot fire while any handle exists). `Document#freed?`
+is the accurate public predicate.
+
+## Consequences
+Measured cost (harness, 1.9.4→1.9.6): visible only on the
+single-cheapest call shape (Element#[] hot loops, ~13-28%); every
+other loop at parity. Accepted as the price of the contract;
+readonly hot loops have the memoized attributes/keys alternatives.
+Do not re-litigate without a C-side lifetime mechanism.

data/docs/adr/0005-autoload-manifest-ordering.md

@@ -0,0 +1,19 @@
+# ADR 0005: the eager FFI require runs after autoload registration
+
+## Context
+Issue #53: eager-loading ffi.rb from inside `module Leptris`
+BEFORE `autoload :XML` was registered let ffi.rb's module opening
+create Leptris::XML first; the registration was shadowed, xml.rb
+never loaded, and the whole API was unreachable
+(constants == [:FFI]).
+
+## Decision
+leptris.rb: register `autoload :XML` first, then the eager
+`require "leptris/xml/ffi"` at top level — ffi.rb's module opening
+triggers the autoload, landing FFI inside the real manifest module;
+a downstream `require "leptris/xml"` is then a no-op. A subprocess
+spec guards the cold path (the in-process suite cannot see it).
+
+## Consequences
+Any new eager require in leptris.rb must come after the autoload
+block. Eager resolution at require time (issue #49) is unchanged.

data/lib/leptris/version.rb

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

data/lib/leptris/xml/css_to_xpath.rb

@@ -35,30 +35,34 @@ module Leptris
 
       module_function
 
-      # Translation is a pure function of the rule string, and real
-      # workloads repeat a small selector vocabulary in loops —
-      # memoize. Failed translations raise before caching.
+      # Translation is a pure function of the rule string AND the
+      # context prefix, and real workloads repeat a small selector
+      # vocabulary in loops — memoize. Failed translations raise
+      # before caching. +prefix+ scopes the result: "//" for
+      # document receivers, ".//" for elements and fragments
+      # (Nokogiri receiver-relative semantics).
       CACHE = {}
       private_constant :CACHE
 
-      def convert(rule)
-        key = rule.to_s
-        CACHE.fetch(key) { CACHE[key] = convert_rule(key) }
+      def convert(rule, prefix: "//")
+        key = "#{prefix}\t#{rule}"
+        CACHE.fetch(key) { CACHE[key] = convert_rule(rule, prefix) }
       end
 
-      def convert_rule(rule)
-        rule.split(COMMA_SPLIT).map { |r| convert_one(r.strip) }.join(" | ")
+      def convert_rule(rule, prefix)
+        rule.split(COMMA_SPLIT)
+          .map { |r| convert_one(r.strip, prefix) }.join(" | ")
       end
 
-      def convert_one(rule)
-        return "//*" if rule == "*"
+      def convert_one(rule, prefix)
+        return "#{prefix}*" if rule == "*"
 
         # Tokenize chain first (handles > and whitespace)
         if rule =~ /\s/ || rule.include?(">")
-          return convert_chain(rule)
+          return convert_chain(rule, prefix)
         end
 
-        convert_simple(rule, prefix: "//")
+        convert_simple(rule, prefix: prefix)
       end
 
       # Parse a single simple selector into (tag, predicates) where
@@ -140,9 +144,9 @@ module Leptris
 
       # Tokenize chain into [sel, op, sel, op, sel, ...] where op is :child or
       # :descendant. Then build XPath.
-      def convert_chain(rule)
+      def convert_chain(rule, prefix)
         tokens = tokenize_chain(rule)
-        build_chain_xpath(tokens)
+        build_chain_xpath(tokens, prefix)
       end
       private_class_method :convert_chain
 
@@ -167,11 +171,11 @@ module Leptris
       end
       private_class_method :tokenize_chain
 
-      def build_chain_xpath(tokens)
+      def build_chain_xpath(tokens, prefix)
         first = tokens.shift
         raise ArgumentError, "empty CSS chain" unless first.is_a?(String)
 
-        xpath = convert_simple(first, prefix: "//")
+        xpath = convert_simple(first, prefix: prefix)
         until tokens.empty?
           op = tokens.shift
           sel = tokens.shift

data/lib/leptris/xml/document.rb

@@ -287,6 +287,22 @@ class Leptris::XML::Document
     @freed.state == :freed || @c_ptr.nil?
   end
 
+  # The thread-global last-failure [line, column] (1-based), or nil
+  # when no error is recorded — the position companion to
+  # Document#last_error; populated by recover parses.
+  def last_error_position
+    line = ::FFI::MemoryPointer.new(:int)
+    column = ::FFI::MemoryPointer.new(:int)
+    begin
+      Leptris::XML::FFI.leptris_last_error_position(line, column)
+      line.read_int.zero? && column.read_int.zero? ? nil :
+        [line.read_int, column.read_int]
+    ensure
+      line.free
+      column.free
+    end
+  end
+
   # The most recent error recorded against this document, or nil.
   def last_error
     msg = Leptris::XML::FFI.leptris_document_last_error(@c_ptr)

data/lib/leptris/xml/document_fragment.rb

@@ -5,6 +5,8 @@
 # the fragment itself isn't part of any document tree but borrows its
 # document's lifetime.
 class Leptris::XML::DocumentFragment
+  include Leptris::XML::Searchable
+
   attr_reader :document, :c_ptr
 
   def initialize(document, c_ptr)

data/lib/leptris/xml/ffi.rb

@@ -553,6 +553,10 @@ module Leptris
         [:leptris_document, :pointer, :pointer], :leptris_status
       attach_function :leptris_status_string, [:leptris_status], :string
       attach_function :leptris_error_message, [:leptris_status], :string
+      # Thread-global last-failure position (error.h): companion to
+      # leptris_last_error; populated by recover parses (#547).
+      attach_function :leptris_last_error_position,
+        [:pointer, :pointer], :void
       # Thread-local since v1.3.0; reliable under the
       # one-document-per-thread contract.
       attach_function :leptris_last_error, [], :string

data/lib/leptris/xml/node.rb

@@ -205,15 +205,9 @@ class Leptris::XML::Node
 
   # Walks the subtree in post-order DFS (matches Nokogiri's semantics).
   #
-  # Specialized hot path: skips the intermediate NodeSet allocation that
-  # Element#children would create, walking via raw FFI calls and wrapping
-  # nodes directly. Saves one Array + one NodeSet allocation per parent
-  # node. For a tree of N nodes that's ~N fewer allocations on a full
-  # traversal.
-  #
-  # Still pays ~2 FFI calls per visited node (first_child + next_sibling).
-  # Beating Nokogiri on this benchmark needs C-side traverse with a
-  # callback (libleptris #273); the per-node FFI cost is the floor.
+  # One FFI call dispatches the whole walk; the C engine invokes the
+  # callback once per visited node (the only per-node cost is the
+  # C-to-Ruby callback dispatch, not FFI round-trips).
   def traverse
     return enum_for(:traverse) unless block_given?
     ensure_alive!

data/lib/leptris/xml/searchable.rb

@@ -44,7 +44,11 @@ module Leptris::XML::Searchable
     handler, ns, _ = parse_search_args(args)
     raise ArgumentError, "namespace bindings not supported in css" if ns && !ns.empty?
     raise ArgumentError, "custom CSS handlers not supported" if handler
-    expr = args.map { |r| Leptris::XML::CssToXPath.convert(r) }.join(" | ")
+    # Nokogiri semantics: css is receiver-relative — absolute "//"
+    # from a Document, descendant ".//" from elements and fragments.
+    prefix = is_a?(Leptris::XML::Document) ? "//" : ".//"
+    expr = args.map { |r| Leptris::XML::CssToXPath.convert(r, prefix: prefix) }
+      .join(" | ")
     xpath(expr)
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.6
+  version: 1.9.7
 platform: ruby
 authors:
 - Ribose Inc.
@@ -65,9 +65,15 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - CLAUDE.md
+- CONTEXT.md
 - LICENSE.md
 - README.adoc
 - Rakefile
+- docs/adr/0001-lockstep-mirror.md
+- docs/adr/0002-utf8-at-the-seam.md
+- docs/adr/0003-readonly-memoization-pattern.md
+- docs/adr/0004-lifetime-guard.md
+- docs/adr/0005-autoload-manifest-ordering.md
 - leptris.gemspec
 - lib/leptris.rb
 - lib/leptris/version.rb