makiri 0.3.0 → 0.4.0

data/README.md

@@ -1,8 +1,9 @@
 # Makiri
 
-Standards-oriented HTML5/XML parsing, CSS selector querying, XPath 1.0 querying,
-and a native XML 1.0 reader/editor for Ruby, powered by Lexbor and a native XPath
-engine - with no libxml2 dependency.
+Makiri is a Ruby library for parsing and querying HTML and XML documents.
+
+It uses [Lexbor](https://lexbor.com/) for HTML parsing and CSS selector matching, and includes a built-in native XPath 1.0 engine and XML 1.0 parser.
+Makiri does not depend on libxml2.
 
 > [!WARNING]
 > Status: early release. APIs and behavior may change before v1.0.
@@ -14,14 +15,12 @@ XPath 1.0 evaluation in its own native engine, with no libxml2 dependency.
 
 * HTML5 parsing via [Lexbor](https://lexbor.com)
   * Makiri uses Lexbor as the parsing backend and provides a Ruby-facing DOM/query layer.
-  * Lexbor-specific behavior is isolated in a thin compatibility layer
-    (`ext/makiri/lexbor_compat/`).
 * CSS selector support via Lexbor
   * Supports Lexbor-backed standard CSS selector querying, including `:is`/`:where`/`:has`
 * Native XPath 1.0 engine
   * XPath is parsed and evaluated by Makiri's own engine, written from scratch.
   * Makiri does not depend on libxml2 for parsing, DOM representation, or XPath evaluation.
-* Native XML 1.0 reader + in-place editor (`Makiri::XML`)
+* Native XML 1.0 parser
   * A strict, non-validating, fail-closed parser with its own node arena (not
     Lexbor's HTML DOM), queried through the same native XPath engine, with
     in-place tree edits (attributes, content, rename, remove).
@@ -81,21 +80,6 @@ ctx.evaluate('//p[@class=$cls]').first.text   # => "Hello"
 
 ### XML (with in-place editing)
 
-`Makiri::XML(source)` parses **XML 1.0** with a native, strict,
-well-formedness-checking parser (no libxml2) and queries it through the same
-native XPath 1.0 engine. `source` is a String or any object responding to
-`#read` (an `IO` / `File` / `StringIO`); read a non-UTF-8 file in binary mode
-(`File.binread`) so its encoding is autodetected. Element-name case and namespaces are preserved. It is
-**fail-closed**: malformed input, a duplicate attribute, or a
-non-`1.0` version declaration raises `Makiri::XML::SyntaxError`, and operations
-XML does not support raise `NotImplementedError` rather than returning a wrong
-result. The tree supports in-place edits and building new subtrees (see below).
-A `<!DOCTYPE ...>` is recognized but its **DTD is not processed** (no
-entity/element declarations are loaded, no external subset is fetched) - so a
-DTD-defined entity reference stays an undefined-entity error and **XXE /
-billion-laughs are structurally impossible**. The doctype's name and identifiers
-are still readable:
-
 ```ruby
 doc = Makiri::XML(<<~XML)
   <feed xmlns="http://www.w3.org/2005/Atom">
@@ -119,10 +103,13 @@ el = doc.at_xpath("//a:entry", ns)
 el.local_name                                  # => "entry"
 el.namespace_uri                               # => "http://www.w3.org/2005/Atom"
 
-doc.css("entry")     # raises NotImplementedError (use #xpath)
+# 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.
+doc.css("entry").length                        # => 2
+doc.css("feed > entry").map { |e| e.at_css("title").text }  # => ["Hello", "World"]
 
 # Serialize back to XML
-doc.to_xml                                 # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<feed ...>...</feed>\n"
+doc.to_xml                                 # => "<?xml version=\"1.0\"?>\n<feed ...>...</feed>\n"
 doc.at_xpath("//a:entry", ns).to_xml       # => "<entry><title>Hello</title></entry>" (no declaration)
 doc.to_xml(pretty: true)                   # indented, element-only content
 
@@ -134,22 +121,7 @@ dtd.external_id  # => "-//W3C//DTD XHTML 1.0//EN"  (alias: #public_id)
 dtd.system_id    # => "x.dtd"
 ```
 
-Comments and processing instructions in the prolog/epilog are document-node
-children (reachable via `//comment()` / `//processing-instruction()` and
-`#children`), and adjacent CDATA is coalesced - matching libxml2 and the XPath
-data model. `#to_xml` / `#to_s` serialize the tree back to XML (`pretty: true`,
-or `indent: n`, for indented element-only content; `encoding: "Shift_JIS"` to
-transcode, with a hex character reference for anything the encoding can't hold);
-a `Document#to_xml` adds the declaration and the DOCTYPE. `#canonicalize` emits
-Inclusive Canonical XML 1.0 (for XML signatures; `comments: true` to keep
-comments), byte-identical to libxml2. CSS is intentionally unavailable for XML
-(Lexbor's selector engine lower-cases names, which breaks XML case/namespace
-matching) - use XPath.
-
-The tree supports in-place mutation - every edit validates its input (names as
-XML 1.0 QNames, values as XML Char) so the tree stays serializable to
-well-formed XML, and a removed node is detached, never freed, so a live wrapper
-that aliases it stays usable:
+The tree supports in-place mutation.
 
 ```ruby
 doc = Makiri::XML(%(<feed xmlns:dc="urn:dc"><entry id="1">Hi</entry><draft/></feed>))
@@ -165,15 +137,9 @@ doc.at_xpath("//draft").remove
 doc.root.to_xml           # => "<feed xmlns:dc=\"urn:dc\"><post dc:k=\"v\">Bye</post></feed>"
 ```
 
-New subtrees can be built too - `Document#create_element` (and
-`#create_text_node` / `#create_comment` / `#create_cdata` /
-`#create_processing_instruction`) make detached nodes, and `#add_child` / `<<`,
-`#add_previous_sibling` / `#before`, `#add_next_sibling` / `#after`, `#replace`
-link them. A node's namespace is resolved against its position **at insertion**
-(a prefixed name binds to the in-scope `xmlns`, an unprefixed element to the
-default namespace), so the same tree results whether you set names before or
-after attaching; an unbound prefix in the live tree fails closed. A node from
-another document is **deep-copied** into the target (the source is untouched):
+XML subtrees can be built with `Document#create_element` and related node factory methods,
+then inserted with `#add_child`, `#before`, `#after`, or `#replace`;
+namespaces are resolved at insertion time, and cross-document nodes are deep-copied.
 
 ```ruby
 doc   = Makiri::XML(%(<feed xmlns="urn:a" xmlns:dc="urn:dc"/>))
@@ -185,34 +151,29 @@ doc.root.add_child(entry)
 doc.to_xml   # => "...<entry dc:id=\"42\"><title>Hello</title></entry>..."
 ```
 
-Supported edits: `#[]=`, `#delete` / `#remove_attribute`, `#content=`, `#name=`,
-`#remove` / `#unlink`, the factories above, and `#add_child` / `<<` /
-`#before` / `#after` / `#replace`. Insertion takes a `Makiri::XML` node or a
-`DocumentFragment` (its children are spliced in); a fragment is parsed by
-`Document#fragment(str)` (bound to the document) or `DocumentFragment.parse(str)`
-(standalone). A raw string handed straight to `#add_child` is **not** accepted -
-parse it into a fragment first. A whole document can also be built from scratch
-with `XML::Document.new` + `#root=` and the factories.
-
-The character encoding is autodetected (XML 1.0 Appendix F): a byte-order mark or
-the `<?xml encoding="..."?>` declaration selects it, so raw bytes (`File.binread`)
-in UTF-16, Shift_JIS, etc. parse correctly and a leading BOM is stripped. A
-concrete String encoding stays authoritative - a BOM or declaration that
-contradicts it is a fatal error, not a silent mis-decode.
-
-Parsing is DoS-bounded by a single arena memory ceiling (default 256 MiB,
-counting node structs and text), which fits every standard document. Raise it
-per parse for an unusually large one:
+`Makiri::XML::Builder` is the Nokogiri-compatible DSL over those factories.
 
 ```ruby
-Makiri::XML(huge_xml, max_bytes: 512 * 1024 * 1024)   # also Makiri::XML::Document.parse(..., max_bytes:)
+builder = Makiri::XML::Builder.new do |xml|
+  xml.feed("xmlns" => "http://www.w3.org/2005/Atom", "xmlns:dc" => "urn:dc") do
+    xml.title("Example Feed")
+    xml.entry("dc:id" => "1") do
+      xml.title("First")
+      xml.summary { xml.cdata("raw <b>html</b>") }
+    end
+  end
+end
+
+builder.to_xml                 # the whole document (with XML declaration)
+builder.doc                    # the Makiri::XML::Document being built
 ```
 
-Conformance is held by a regression net: the **W3C XML Conformance Test Suite**
-(`rake conformance:xmlconf`, 100% of the in-scope non-validating XML-1.0 tests),
-an XPath 1.0 differential vs Nokogiri/libxml2 (`rake conformance:xpath_xml`), and
-property-based testing that requires Makiri's tree to be byte-identical to
-Nokogiri's over generated documents (`rake conformance:xml_pbt`).
+XML parsing is bounded by an arena memory limit, 256 MiB by default,
+and unusually large documents can raise it with `max_bytes:`.
+
+```ruby
+Makiri::XML(huge_xml, max_bytes: 512 * 1024 * 1024)   # also Makiri::XML::Document.parse(..., max_bytes:)
+```
 
 ## Non-goals (v1.0)
 
@@ -271,14 +232,48 @@ Detailed, test-backed notes live in `spec/conformance/README.md`.
 
 ### CSS
 
-* jQuery/Nokogiri CSS extensions are not supported (`:contains`, `:gt`, `:lt`, `:eq`, `:first`, ...)
-  * Makiri uses Lexbor's standards-only selector engine.
-    Use XPath (`xpath("//p[contains(., 'x')]")`) or Enumerable (`css('li')[1]`).
+* 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.
     Standard Level-4 selectors (`:is` / `:where` / `:has`) are supported; some of which Nokogiri rejects.
+  * `:lexbor-contains("text")` **is** supported (on both HTML and XML) - Lexbor's
+    spelling of the jQuery `:contains()` substring filter, matching an element
+    whose text contains the string; append ` i` (`:lexbor-contains("text" i)`)
+    for an ASCII case-insensitive match. (Nokogiri's name `:contains` is not an
+    alias.) Like Lexbor's matcher, it tests the element's **immediate child text
+    nodes** (not the deep string-value), so HTML and XML agree; on XML it lowers
+    to XPath `child::text()[contains(., "text")]`.
+* Untyped `:*-of-type` (`:first-of-type`, `:nth-of-type(an+b)`, ... with no type
+  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.
 * Type selectors are ASCII case-insensitive (CSS-correct for HTML; `LI` matches `<li>`)
   * `Nokogiri::HTML5` is case-sensitive there.
-* Class/ID selectors are matched case-insensitively regardless of quirks mode (a Lexbor behaviour)
-  * In a no-quirks document browsers and `Nokogiri::HTML5` match them case-sensitively.
+
+## Conformance
+
+The XPath engine and XML parser are original code, so their correctness is held by
+differential and standards harnesses in `spec/conformance/`.
+The HTML XPath and CSS suites are differentials against **`Nokogiri::HTML5`**
+(Gumbo / WHATWG, never libxml2's non-conformant HTML4 parser): both sides parse
+HTML5, so the DOM is isomorphic and results are compared node-for-node. HTML
+parsing itself is checked against the WHATWG html5lib-tests corpus, and
+XPath-over-HTML semantics additionally against browsers via a WPT port.
+See also [`spec/conformance/README.md`](spec/conformance/README.md).
+
+| Suite | Input | Oracle | `rake` task |
+|---|---|---|---|
+| HTML parsing | HTML | WHATWG html5lib-tests (expected-tree corpus) | `conformance:html5` |
+| XPath 1.0 | HTML | `Nokogiri::HTML5` (libxml2 XPath) — differential | `conformance:xpath` |
+| XPath over HTML | HTML | browsers (WPT `domxpath`, hand-ported; runs under `rake spec`) | — |
+| CSS selectors | HTML | `Nokogiri::HTML5#css` — differential | `conformance:css` |
+| Well-formedness | XML | W3C XML Conformance Test Suite | `conformance:xmlconf` |
+| XPath 1.0 | XML | `Nokogiri::XML` — differential | `conformance:xpath_xml` |
+| Parsed tree (property-based) | XML | `Nokogiri::XML` — differential | `conformance:xml_pbt` |
+| CSS selectors | XML | `Nokogiri::XML` — differential | `conformance:css_xml` |
 
 ## Requirements
 
@@ -295,6 +290,15 @@ bundle exec rake compile
 bundle exec rake spec
 ```
 
+### Vendored Lexbor version
+
+`vendor/lexbor` is pinned to `3a2d595` (`v3.0.0-25`), an untagged `master`
+commit, for fixes that v3.0.0 lacks: two upstreamed CSS-selector fixes (class/ID
+case-sensitivity in quirks mode, and prefix-less type-selector namespacing), a
+heap-overflow fix in the `:lexbor-contains()` parser, and other post-v3.0.0
+bugfixes. Lexbor stays vanilla; we return to a release tag once one ships after
+v3.0.0. See `CLAUDE.md` for details.
+
 ## License
 
 Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

data/Rakefile

@@ -4,6 +4,7 @@ require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 require "rake/extensiontask"
 require "shellwords"
+require "tmpdir"
 
 GEMSPEC = Gem::Specification.load("makiri.gemspec")
 
@@ -35,6 +36,59 @@ RSpec::Core::RakeTask.new(:spec)
 
 task default: %i[compile spec]
 
+# `rake spec:valgrind` - run the spec suite under Valgrind memcheck via
+# ruby_memcheck (Linux CI; see .github/workflows/valgrind.yml). The gem ships
+# Ruby's own Valgrind suppression files (matched by Ruby version) and filters
+# the report down to errors whose stack touches our extension, so we no longer
+# have to fetch ruby.supp from ruby/ruby (that path was removed upstream).
+#
+# We keep this job's historical contract: catch *use of uninitialised values*
+# and *invalid reads/writes* (incl. intra-arena overflows) - NOT leaks (leak
+# detection stays with `rake leaks`). So we override ruby_memcheck's defaults,
+# which disable undef-value errors and turn on full leak-check.
+#
+# `filter_all_errors: true` is essential: by default ruby_memcheck only applies
+# its "stack must touch the makiri binary" filter to *leak*-kind errors
+# (`ValgrindError#should_filter? = filter_all_errors? || kind_leak?`), so every
+# uninitialised-value report is surfaced regardless of where it comes from. Ruby's
+# conservative GC (machine-context scan, RVALUE flag aging, free-at-exit teardown)
+# legitimately reads uninitialised words, and the bundled ruby.supp does not cover
+# the free-at-exit / subprocess stacks the `:isolated` specs spin up under
+# `--trace-children=yes` - which buried the run in ~3500 pure-Ruby false positives.
+# Filtering all error kinds by the same binary-touch rule keeps the gate scoped to
+# *our* code: a real uninit/invalid access in mkr_*/Lexbor still has a makiri frame
+# and is still reported.
+#
+# Guarded: ruby_memcheck lives in the optional :valgrind bundler group, so a
+# normal `bundle exec rake` (without that group) must not fail to load.
+begin
+  require "ruby_memcheck"
+  require "ruby_memcheck/rspec/rake_task"
+
+  RubyMemcheck.config(
+    binary_name: "makiri",
+    filter_all_errors: true,    # apply the binary-touch filter to ALL error kinds,
+                                # not just leaks (see note above) - drops Ruby's own
+                                # GC uninitialised-value noise, keeps mkr_* reports
+    valgrind_options: [
+      "--num-callers=50",
+      "--error-limit=no",
+      "--trace-children=yes",   # spec processes may fork
+      "--undef-value-errors=yes", # the point of this job (ruby_memcheck defaults to =no)
+      "--track-origins=yes",    # report where an uninitialised value came from
+      "--leak-check=no",        # leaks are `rake leaks`' job, not this one
+    ],
+  )
+
+  namespace :spec do
+    desc "Run the spec suite under Valgrind memcheck (ruby_memcheck; needs the " \
+         ":valgrind bundler group and the valgrind binary)"
+    RubyMemcheck::RSpec::RakeTask.new(valgrind: :compile)
+  end
+rescue LoadError
+  # ruby_memcheck not installed (optional :valgrind group absent) - skip the task.
+end
+
 namespace :security do
   desc "Run mechanical C safety lint over ext/makiri"
   task :clint do
@@ -81,6 +135,17 @@ def asan_runtime_path
   nil
 end
 
+def libfuzzer_available?
+  cxx = ENV["CXX"].to_s.empty? ? "clang++" : ENV["CXX"]
+  Dir.mktmpdir("makiri-libfuzzer-check") do |dir|
+    src = File.join(dir, "check.cc")
+    exe = File.join(dir, "check")
+    File.write(src, "extern \"C\" int LLVMFuzzerTestOneInput(const unsigned char*, unsigned long){return 0;}\n")
+    return system(cxx, "-fsanitize=fuzzer,address,undefined", src, "-o", exe,
+                  out: File::NULL, err: File::NULL)
+  end
+end
+
 # The compiled extension, and whether it carries sanitizer instrumentation, so
 # `fuzz:sanitize SKIP_BUILD=1` can refuse to run a plain (non-ASan) build.
 def ext_bundle_path
@@ -116,6 +181,65 @@ task :sanitize do
   sh(env, "#{FileUtils::RUBY} -S rspec")
 end
 
+desc "Measure C coverage of OUR sources (clang source-based) over the spec suite. " \
+     "Prints an llvm-cov region+branch report (excludes vendored Lexbor) and writes " \
+     "a line-level detail file to tmp/coverage/show.txt."
+task :coverage do
+  require "fileutils"
+  dir = File.expand_path("tmp/coverage")
+  FileUtils.rm_rf(dir)
+  FileUtils.mkdir_p(dir)
+
+  # Instrument only our sources (Lexbor is built separately, uninstrumented).
+  sh({ "MAKIRI_COVERAGE" => "1" }, "#{FileUtils::RUBY} -S rake clean compile")
+  # %p -> PID, so any forked spec process gets its own raw profile.
+  sh({ "LLVM_PROFILE_FILE" => File.join(dir, "makiri-%p.profraw") }, "#{FileUtils::RUBY} -S rspec")
+
+  profdata = File.join(dir, "makiri.profdata")
+  bundle   = "lib/makiri/makiri.bundle"
+  ignore   = "(vendor/lexbor|/usr/|/Library/|ruby/|rubygems)"
+  sh "xcrun llvm-profdata merge -sparse #{dir}/*.profraw -o #{profdata}"
+  sh "xcrun llvm-cov report #{bundle} -instr-profile=#{profdata} " \
+     "-ignore-filename-regex='#{ignore}' -show-branch-summary"
+  show = File.join(dir, "show.txt")
+  sh "xcrun llvm-cov show #{bundle} -instr-profile=#{profdata} " \
+     "-ignore-filename-regex='#{ignore}' -show-branches=count -show-line-counts-or-regions > #{show}"
+  puts "\ncoverage line/branch detail: #{show}"
+  puts "(coverage build left in place; run `rake clean compile` to restore a normal build)"
+end
+
+desc "Like :sanitize but also builds the vendored Lexbor under ASan, so overflows " \
+     "INSIDE Lexbor's mraw arena are caught (slow: full Lexbor rebuild). Runs the " \
+     "spec suite, or FUZZ_ARGS via the fuzzer when set."
+task "sanitize:lexbor" do
+  sanitize = ENV["MAKIRI_SANITIZE"] || "address,undefined"
+  sanitize.include?("address") or
+    abort "sanitize:lexbor needs an address build (MAKIRI_SANITIZE must include 'address')"
+
+  # MAKIRI_SANITIZE_LEXBOR makes extconf build Lexbor with -DLEXBOR_BUILD_WITH_ASAN
+  # (enabling its mraw poisoning); the build-mode stamp auto-rebuilds Lexbor on the
+  # plain<->asan switch, so no manual clean:lexbor is needed before or after.
+  build_env = { "MAKIRI_SANITIZE" => sanitize, "MAKIRI_SANITIZE_LEXBOR" => "1" }
+  sh(build_env, "#{FileUtils::RUBY} -S rake clean compile")
+
+  env = {
+    "ASAN_OPTIONS"  => "detect_leaks=0:detect_container_overflow=0:" \
+                       "detect_odr_violation=0:abort_on_error=1:halt_on_error=1",
+    "UBSAN_OPTIONS" => "print_stacktrace=1:halt_on_error=1",
+  }
+  runtime = asan_runtime_path or
+    abort "sanitize:lexbor: could not locate the ASan runtime for #{RbConfig::CONFIG['CC']}"
+  preload = RbConfig::CONFIG["target_os"] =~ /darwin/ ? "DYLD_INSERT_LIBRARIES" : "LD_PRELOAD"
+  env[preload] = runtime
+  puts "sanitize:lexbor: preloading #{runtime} via #{preload}"
+
+  if ENV["FUZZ_ARGS"]
+    sh(env, "#{FileUtils::RUBY} -Ilib spec/fuzz/run.rb #{ENV['FUZZ_ARGS']}")
+  else
+    sh(env, "#{FileUtils::RUBY} -S rspec")
+  end
+end
+
 desc "Run the robustness fuzzer (override options via FUZZ_ARGS)"
 task fuzz: :compile do
   sh "#{FileUtils::RUBY} -Ilib spec/fuzz/run.rb #{ENV['FUZZ_ARGS']}"
@@ -131,6 +255,25 @@ task "fuzz:mutate": :compile do
   sh "#{FileUtils::RUBY} -Ilib spec/fuzz/run.rb --target mutate #{ENV['FUZZ_ARGS']}"
 end
 
+desc "Malloc-leak gate (macOS `leaks`): fails on per-call leak stacks through the ext"
+task leaks: :compile do
+  # ASan runs with detect_leaks=0 (Ruby/Lexbor are uninstrumented), so plain
+  # leaks are otherwise never machine-checked; see script/check_leaks.rb.
+  sh "#{FileUtils::RUBY} script/check_leaks.rb"
+end
+
+desc "OOM-injection gate: rebuild with MAKIRI_ALLOC_INJECT=1 and sweep every core " \
+     "allocation site, verifying each failure fails closed (clean raise or " \
+     "baseline-identical result, never truncated output)"
+task :oom do
+  # The hook is compiled in only under MAKIRI_ALLOC_INJECT=1 (zero overhead in
+  # a normal build), so this needs its own rebuild; see
+  # script/check_alloc_failures.rb for the protocol and the property gated.
+  sh({ "MAKIRI_ALLOC_INJECT" => "1" }, "#{FileUtils::RUBY} -S rake clean compile")
+  sh "#{FileUtils::RUBY} -Ilib script/check_alloc_failures.rb"
+  puts "(injection build left in place; run `rake clean compile` to restore a normal build)"
+end
+
 desc "Run the performance benchmark (Makiri vs Nokogiri reference)"
 task bench: :compile do
   # Run outside the bundle so the bench-only gems (nokogiri, benchmark-ips)
@@ -190,10 +333,26 @@ namespace :conformance do
       sh "#{FileUtils::RUBY} -Ilib spec/conformance/css_diff.rb #{ENV['CSS_ARGS']}"
     end
   end
+
+  desc "XML CSS-selector differential conformance: Makiri::XML vs Nokogiri::XML"
+  task css_xml: :compile do
+    Bundler.with_unbundled_env do
+      sh "#{FileUtils::RUBY} -Ilib spec/conformance/xml_css_diff.rb #{ENV['CSS_XML_ARGS']}"
+    end
+  end
+
+  desc "XML Builder differential conformance: Makiri::XML::Builder vs Nokogiri::XML::Builder"
+  task builder: :compile do
+    Bundler.with_unbundled_env do
+      sh "#{FileUtils::RUBY} -Ilib spec/conformance/builder_diff.rb #{ENV['BUILDER_ARGS']}"
+    end
+  end
 end
 
 desc "Run all conformance suites"
-task conformance: %w[conformance:html5 conformance:xpath conformance:css conformance:xmlconf conformance:xpath_xml]
+task conformance: %w[conformance:html5 conformance:xpath conformance:css
+                     conformance:xmlconf conformance:xpath_xml conformance:css_xml
+                     conformance:builder]
 
 namespace :fuzz do
   # Run the fuzzer under the sanitizer. Toggles (all via env):
@@ -233,14 +392,46 @@ namespace :fuzz do
     if ENV["FUZZ_ARGS"]
       sh(env, "#{FileUtils::RUBY} -Ilib spec/fuzz/run.rb #{ENV['FUZZ_ARGS']}")
     else
-      iso  = %w[1 true yes].include?(ENV["FAST"].to_s.downcase) ? "" : "--isolated"
+      iso  = %w[1 true yes].include?(ENV["ISOLATED"].to_s.downcase) ? "--isolated" : ""
       secs = ENV["FUZZ_TIME"] || "90"
       # Cover every surface under the sanitizer: the query engine (XPath/CSS over
       # parsed fixtures), the XML parser (hostile documents), and the XML mutation
       # surface (random edit sequences + invariants).
-      ["", "--target xml", "--target mutate"].each do |surface|
+      ["", "--target xml", "--target mutate", "--target xmlcss"].each do |surface|
         sh(env, "#{FileUtils::RUBY} -Ilib spec/fuzz/run.rb #{surface} #{iso} --time #{secs}".squeeze(" ").strip)
       end
     end
   end
+
+  # Coverage-guided libFuzzer harnesses for the pure-C surfaces (XML parser and
+  # XPath compile+eval).  These are Ruby-free standalone binaries, so they run
+  # directly under clang's libFuzzer driver without the Ruby interpreter.
+  # They complement the Ruby-based robustness fuzzer by providing coverage
+  # feedback and 2-3 orders of magnitude faster execution for the C core.
+  desc "Build the libFuzzer harnesses (requires clang with libFuzzer support)"
+  task :libfuzzer_build => :compile do
+    libfuzzer_available? or
+      abort "fuzz:libfuzzer_build: #{ENV['CXX'] || 'clang++'} cannot link libFuzzer. " \
+            "Install an LLVM clang with libFuzzer support and run with " \
+            "CLANG=/path/to/clang CXX=/path/to/clang++."
+    Dir.chdir("ext/makiri/fuzz") do
+      sh "make clean"
+      sh "make all"
+    end
+  end
+
+  desc "Run the libFuzzer coverage-guided harnesses (default: 60s per target)"
+  task :libfuzzer => :libfuzzer_build do
+    time = ENV["FUZZ_TIME"] || "60"
+    Dir.chdir("ext/makiri/fuzz") do
+      sh "mkdir -p corpus/xml corpus/xpath"
+      sh "./xml_fuzz -max_total_time=#{time} -max_len=4096 corpus/xml"
+      sh "./xpath_fuzz -max_total_time=#{time} -max_len=4096 corpus/xpath"
+    end
+  end
+end
+
+desc "Show code statistics"
+task :stats do
+  sh "tokei lib ext spec script --exclude tmp --exclude vendor --exclude docs"
 end