moxml 0.5.146 → 0.5.148

data/lib/moxml/node.rb

@@ -847,6 +847,18 @@ module Moxml
     def self.wrap_with(node, context, adapter)
       return nil if node.nil?
 
+      # Identity natives ARE the canonical wrapper (leptris C-mint):
+      # @native is self, so canonicalization, the cache probes and
+      # the re-mint below all answer the receiver. One native ivar
+      # read decides; shells (@native != self) take the full path.
+      # The C mint leaves the node un-primed (@context unset) — prime
+      # on first wrap. Conditionally: an already-primed identity (a
+      # walked node) must not lose @parent_node to a re-prime.
+      if node.is_a?(Node) && node.instance_variable_get(:@native).equal?(node)
+        node.prime_contract(node, context, adapter) unless node.instance_variable_defined?(:@context)
+        return node
+      end
+
       # One C node may have several Ruby representations (leptris
       # native/binding duality, moxml#311); every wrap resolves to
       # the canonical one so memo holders share one invalidation

data/lib/moxml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Moxml
-  VERSION = "0.5.146"
+  VERSION = "0.5.148"
 end

data/spec/consistency/divergence_register_spec.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Divergence register linkage (TODO.model/02): the register
+# (docs/_pages/divergences.adoc) and the consistency suite must stay
+# mechanically consistent — every capability-related skip cites a
+# register ID, every register entry is cited by at least one spec, and
+# no spec cites an unregistered ID.
+RSpec.describe "divergence register linkage" do
+  REGISTER_PATH = "docs/_pages/divergences.adoc" # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+  SCAN_GLOBS = %w[spec/consistency/**/*.rb spec/moxml/**/*.rb].freeze # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+  NEXT_GATE = [ # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+    /same engine as/, # engine dedup, not a divergence
+    /source_adapter == target_adapter/, # self round-trip
+    /MAX_SIZE/, # size guard
+    /AVAILABLE_ADAPTERS\.include/, # availability filter
+    /skip_shapes/,              # shape routing (IDs cited above)
+    /leptris_fixed\?/,          # version gate
+    /source_elements/,          # data-presence guard
+    /next unless match/,        # scanner-internal guard
+  ].freeze
+
+  # Version/availability gates are not divergences: a binding too old
+  # or an adapter not installed is a deployment fact, not an
+  # engine-vs-model difference at equal versions.
+  GATE = [ # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+    /unavailable/i, /not available/, /predates/, /not installed/i,
+    /not present/i, /requires/i, /required\z/, /has no \S+ face/,
+    /lacks the /, /carries /, /degraded below/, /lockstep/i,
+    /unreleased/i, /stood down/, /recovered without/,
+    /Only \S+ available in CI/i, /adapter-specific/i, /noblanks/,
+    /SKIP_ parse flags/, /engine < \d/
+  ].freeze
+
+  def register_ids
+    File.readlines(REGISTER_PATH)
+      .filter_map { |line| line[/\A\|\s*(D-\d+)\s*$/, 1] }
+      .uniq
+  end
+
+  def spec_files
+    SCAN_GLOBS.flat_map { |g| Dir[g] }.uniq
+  end
+
+  def cited_ids
+    spec_files.flat_map { |path| File.readlines(path) }
+      .flat_map { |line| line.scan(/D-\d+/) }
+      .uniq
+  end
+
+  it "has a register with entries" do
+    expect(register_ids).not_to be_empty
+  end
+
+  it "requires capability-related skips to cite a register ID" do
+    offenders = []
+    spec_files.each do |path|
+      File.readlines(path).each_with_index do |line, i|
+        next unless (msg = line[/skip\s+[&(]?\s*["'](.*?)["']/, 1])
+
+        next if GATE.any? { |re| re.match?(msg) }
+        next if msg.match?(/D-\d+/)
+
+        offenders << "#{path}:#{i + 1} #{msg.strip[0, 60]}"
+      end
+    end
+    expect(offenders).to be_empty,
+                         "capability skips must cite a divergence-register " \
+                         "ID (D-NN): #{offenders.join('; ')}"
+  end
+
+  it "requires adapter-exempting next-guards to cite a nearby register ID" do
+    offenders = []
+    spec_files.each do |path|
+      next if path.end_with?("divergence_register_spec.rb")
+
+      lines = File.readlines(path)
+      lines.each_with_index do |line, i|
+        next unless line.match?(/^\s*next\s+(if|unless)\s/)
+        next if NEXT_GATE.any? { |re| re.match?(line) }
+        next if line.match?(/D-\d+/)
+
+        context = lines[[i - 4, 0].max...i] + lines[(i + 1)..(i + 4)].to_a
+        next if context.any? { |l| l.match?(/D-\d+/) }
+
+        offenders << "#{path}:#{i + 1} #{line.strip[0, 60]}"
+      end
+    end
+    expect(offenders).to be_empty,
+                         "adapter-exempting next-guards must cite a " \
+                         "divergence-register ID (D-NN) on or above the " \
+                         "line: #{offenders.join('; ')}"
+  end
+
+  it "cites every register entry from at least one spec" do
+    missing = register_ids - cited_ids
+    expect(missing).to be_empty,
+                       "register entries never cited by a spec: " \
+                       "#{missing.join(', ')}"
+  end
+
+  it "never cites an unregistered divergence ID" do
+    orphans = cited_ids - register_ids
+    expect(orphans).to be_empty,
+                       "specs cite IDs missing from the register: " \
+                       "#{orphans.join(', ')}"
+  end
+end

data/spec/consistency/document_text_spec.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Issue #400: documents are container nodes — Document#text
+# concatenates descendant text (Nokogiri's Document#text contract).
+# The base Node#text answered "" and silently emptied consumers'
+# content-preservation checks (canon's formatter asserted through
+# doc.text).
+RSpec.describe "Document#text concatenates descendant text" do
+  Moxml::Adapter::AVAILABLE_ADAPTERS.each do |adapter_name|
+    context "with #{adapter_name}" do
+      let(:ctx) { Moxml.new(adapter_name) }
+
+      it "answers the concatenated descendant text" do
+        doc = ctx.parse("<r><a>x</a><b>y</b></r>")
+        expect(doc.text).to eq("xy")
+      end
+
+      it "matches root.text (both containers recurse)" do
+        doc = ctx.parse("<r><a>x</a><b>y</b></r>")
+        expect(doc.text).to eq(doc.root.text)
+      end
+
+      it "answers an empty string for element-free documents" do
+        expect(ctx.parse("<r/>").text).to eq("")
+      end
+    end
+  end
+end

data/spec/consistency/eol_normalization_spec.rb

@@ -20,7 +20,7 @@ require "spec_helper"
 #                     binding release vending that engine rides
 #                     (gate: binding 1.9.240).
 RSpec.describe "XML line-ending normalization" do
-  ADAPTERS = %i[leptris nokogiri ox oga rexml libxml].freeze # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+  EOL_NORMALIZATION_ADAPTERS = %i[leptris nokogiri ox oga rexml libxml].freeze # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
 
   def with_adapter(name)
     ctx = Moxml.new(name)
@@ -37,10 +37,10 @@ RSpec.describe "XML line-ending normalization" do
   end
 
   it "normalizes CRLF and lone CR to LF in text content" do
-    ADAPTERS.each do |name|
+    EOL_NORMALIZATION_ADAPTERS.each do |name|
       next unless leptris_fixed?(name)
 
-      skip "oga preserves raw CR (upstream)" if name == :oga
+      skip "D-02: oga preserves raw CR (upstream)" if name == :oga
 
       with_adapter(name) do |ctx|
         text = ctx.parse("<r>a\r\nb\rc</r>").root.children.first
@@ -50,10 +50,10 @@ RSpec.describe "XML line-ending normalization" do
   end
 
   it "normalizes EOL inside CDATA content" do
-    ADAPTERS.each do |name|
+    EOL_NORMALIZATION_ADAPTERS.each do |name|
       next unless leptris_fixed?(name)
 
-      skip "oga preserves raw CR (upstream)" if name == :oga
+      skip "D-02: oga preserves raw CR (upstream)" if name == :oga
 
       with_adapter(name) do |ctx|
         cdata = ctx.parse("<r><![CDATA[a\r\nb]]></r>").root.children.first
@@ -63,11 +63,11 @@ RSpec.describe "XML line-ending normalization" do
   end
 
   it "preserves CR from character references" do
-    ADAPTERS.each do |name|
+    EOL_NORMALIZATION_ADAPTERS.each do |name|
       next unless leptris_fixed?(name)
 
-      skip "ox collapses &#13; to LF (upstream)" if name == :ox
-      skip "oga preserves raw CR (upstream)" if name == :oga
+      skip "D-03: ox collapses &#13; to LF (upstream)" if name == :ox
+      skip "D-02: oga preserves raw CR (upstream)" if name == :oga
 
       with_adapter(name) do |ctx|
         text = ctx.parse("<r>a&#13;b</r>").root.children.first

data/spec/consistency/loud_degradation_spec.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Loud degradation (processing model, "Errors and loud degradation"):
+# a capability an engine cannot deliver must answer the contract or
+# raise the named error — never a divergent answer. Probed across all
+# available adapters; the capability lists mirror the adapters'
+# actual engine backing.
+RSpec.describe "loud capability contracts" do
+  available = Moxml::Adapter::AVAILABLE_ADAPTERS
+  xslt_capable = %i[nokogiri leptris] & available
+  html_capable = %i[nokogiri leptris] & available
+
+  let(:sheet) do
+    %(<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">) \
+      "<xsl:template match='/'><o/></xsl:template></xsl:stylesheet>"
+  end
+
+  (available - xslt_capable).each do |name|
+    it "raises NotImplementedError for XSLT on #{name}" do
+      ctx = Moxml.new(name)
+      expect { ctx.xslt(sheet) }.to raise_error(Moxml::NotImplementedError)
+    end
+  end
+
+  (available - html_capable).each do |name|
+    it "raises NotImplementedError for to_xhtml on #{name}" do
+      doc = Moxml.new(name).parse("<r><a/></r>")
+      expect { doc.to_xhtml }.to raise_error(Moxml::NotImplementedError)
+    end
+
+    it "raises AdapterError for to_html on #{name}" do
+      doc = Moxml.new(name).parse("<r><a/></r>")
+      expect { doc.to_html }.to raise_error(Moxml::AdapterError)
+    end
+  end
+
+  xslt_capable.each do |name|
+    it "compiles a stylesheet on #{name}" do
+      expect(Moxml.new(name).xslt(sheet)).to be_a(Moxml::XSLT::Stylesheet)
+    end
+  end
+end

data/spec/consistency/model_coverage_audit_spec.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Model coverage matrix (TODO.model/03): every face family of the
+# processing model is governed for every adapter — covered by a pin
+# (the consistency/contract spec that asserts equivalence), exempt via
+# a registered divergence (adapter => D-ID), or loud (adapter =>
+# the named error class). An unpinned family is an ungoverned cell:
+# this audit fails until it has one of the three.
+# See docs/_references/processing-model.adoc for the model itself.
+RSpec.describe "model coverage matrix" do
+  MODEL_MATRIX = { # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+    "document order and children listing" => {
+      pin: "spec/consistency/adapter_parity_spec.rb",
+    },
+    "name resolution" => {
+      pin: "spec/consistency/xpath_idioms_spec.rb",
+    },
+    "namespace resolution and bindings normalization" => {
+      pin: "spec/consistency/xpath_idioms_spec.rb",
+    },
+    "attribute access" => {
+      pin: "spec/moxml/attribute_resolver_spec.rb",
+    },
+    "text/content/raw_content" => {
+      pin: "spec/moxml/text_spec.rb",
+    },
+    "parsing modes and diagnostics" => {
+      pin: "spec/moxml/document_parse_diagnostics_spec.rb",
+    },
+    "EOL normalization" => {
+      pin: "spec/consistency/eol_normalization_spec.rb",
+      exempt: { oga: "D-02", ox: "D-03" },
+    },
+    "entity modes" => {
+      pin: "spec/moxml/entity_spec.rb",
+    },
+    "XPath evaluation and declared idioms" => {
+      pin: "spec/consistency/xpath_idioms_spec.rb",
+      exempt: { oga: "D-01" },
+    },
+    "serialization shapes (xml/html/xhtml)" => {
+      pin: "spec/moxml/xhtml_output_spec.rb",
+    },
+    "indentation knobs" => {
+      pin: "spec/moxml/to_html_spec.rb",
+      exempt: { oga: "D-09", ox: "D-09", headed_ox: "D-09",
+                libxml: "D-09", leptris: "D-09" },
+    },
+    "canonicalization" => {
+      pin: "spec/moxml/c14n/adapter_delegation_spec.rb",
+      exempt: { oga: "D-04", ox: "D-05", headed_ox: "D-05" },
+    },
+    "XSLT" => {
+      pin: "spec/consistency/xslt_spec.rb",
+      loud: { oga: "Moxml::NotImplementedError",
+              ox: "Moxml::NotImplementedError",
+              headed_ox: "Moxml::NotImplementedError",
+              rexml: "Moxml::NotImplementedError",
+              libxml: "Moxml::NotImplementedError" },
+    },
+    "SAX" => {
+      pin: "spec/moxml/sax_spec.rb",
+    },
+    "materialization" => {
+      pin: "spec/moxml/plan_conformance_spec.rb",
+    },
+    "loud capability contracts" => {
+      pin: "spec/consistency/loud_degradation_spec.rb",
+    },
+  }.freeze
+
+  def register_ids
+    File.readlines("docs/_pages/divergences.adoc")
+      .filter_map { |line| line[/\A\|\s*(D-\d+)\s*$/, 1] }
+      .uniq
+  end
+
+  it "governs every face family with a pin" do
+    unpinned = MODEL_MATRIX.reject { |_, cell| cell[:pin] }.keys
+    expect(unpinned).to be_empty,
+                        "ungoverned face families (no pin): " \
+                        "#{unpinned.join(', ')}"
+  end
+
+  it "points every pin at an existing spec" do
+    missing = MODEL_MATRIX.filter_map do |family, cell|
+      family unless cell[:pin] && File.exist?(cell[:pin])
+    end
+    expect(missing).to be_empty, "pins missing on disk: #{missing.join(', ')}"
+  end
+
+  it "exempts adapters only via registered divergences" do
+    unknown = MODEL_MATRIX.flat_map do |family, cell|
+      (cell[:exempt] || {}).filter_map do |adapter, id|
+        "#{family}: #{adapter} -> #{id}" unless register_ids.include?(id)
+      end
+    end
+    expect(unknown).to be_empty,
+                       "exemptions cite unregistered IDs: #{unknown.join('; ')}"
+  end
+
+  it "declares loud cells only with named Moxml errors" do
+    bad = MODEL_MATRIX.flat_map do |family, cell|
+      (cell[:loud] || {}).filter_map do |adapter, error|
+        "#{family}: #{adapter} -> #{error}" unless error.start_with?("Moxml::")
+      end
+    end
+    expect(bad).to be_empty,
+                   "loud cells must name Moxml errors: #{bad.join('; ')}"
+  end
+end

data/spec/consistency/spec_constant_uniqueness_spec.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Checker integrity (TODO.model/06): top-level constant names in spec
+# files all resolve through Object inside example blocks, so the same
+# name defined by two files makes the last-loaded file win — the 0.5.143
+# CORPUS collision made the battery fail ~50% of runs with a foreign
+# corpus. This guard kills the class.
+RSpec.describe "spec-file top-level constant uniqueness" do
+  it "defines each constant name in at most one spec/support file" do
+    seen = {}
+
+    Dir["spec/**/*.rb"].each do |path|
+      File.readlines(path).each_with_index do |line, i|
+        match = line.match(/\A\s*([A-Z][A-Z0-9_]*)\s*=[^=]/)
+        next unless match
+
+        name = match[1]
+        expect(seen)
+          .not_to have_key(name),
+                  "#{name} defined at #{seen[name]} and #{path}:#{i + 1} " \
+                  "— constants inside example blocks collide through " \
+                  "Object; give one file a unique name"
+        seen[name] = "#{path}:#{i + 1}"
+      end
+    end
+  end
+end

data/spec/consistency/xpath_idioms_spec.rb

@@ -42,7 +42,7 @@ RSpec.describe "XPath idioms across adapters" do
         if adapter_name == :oga
           # oga's own Ruby XPath engine has no xmlns: default-ns
           # support (third-party; explicit bindings work).
-          skip "oga's XPath engine does not implement the xmlns: idiom"
+          skip "D-01: oga's XPath engine does not implement the xmlns: idiom"
         end
       end
 

data/spec/moxml/adapter/leptris_contract_reads_spec.rb

@@ -130,4 +130,33 @@ RSpec.describe "leptris Identity contract reads" do
       expect(el.text).to eq("v")
     end
   end
+
+  describe "children" do
+    it "answers without the adapter children crossing (children_read)" do
+      unless Leptris::XML::NativeNode.method_defined?(:children_read)
+        skip "binding #{Leptris::VERSION} has no children_read face"
+      end
+      doc = ctx.parse("<root><item>v</item></root>")
+      el = doc.root.children.first
+
+      singleton = Moxml::Adapter::Leptris.singleton_class
+      singleton.send(:alias_method, :children_without_walk, :children)
+      singleton.send(:define_method, :children) { |*| raise "adapter children crossing" }
+      begin
+        kids = el.children
+        expect(kids.to_a.map(&:name)).to eq(["text"])
+      ensure
+        singleton.send(:alias_method, :children, :children_without_walk)
+        singleton.send(:remove_method, :children_without_walk)
+      end
+    end
+
+    it "returns a NodeSet carrying the contract wrappers" do
+      doc = ctx.parse("<root><item>v</item></root>")
+      kids = doc.root.children.first.children
+      expect(kids).to be_a(Moxml::NodeSet)
+      expect(kids.to_a.first.name).to eq("text")
+      expect(kids.to_a.first.content).to eq("v")
+    end
+  end
 end

data/spec/moxml/adapter/leptris_detached_text_spec.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Issue #401: Text#content= on a detached (parentless) node answered
+# the engine's bare "Invalid argument" with no indication of the cause.
+# The leptris adapter now re-raises it as a named Moxml error carrying
+# the detachment. Created-unattached nodes work (probe), so only the
+# failing detachment is re-raised.
+RSpec.describe "detached text content= names the cause" do
+  let(:ctx) { Moxml.new(:leptris) }
+
+  it "answers removed text nodes: mutable on fixed engines (1.9.374+), named error before" do
+    doc = ctx.parse("<r><a>x</a><b>y</b></r>")
+    text = doc.root.children[0].children[0]
+    text.remove
+
+    if Gem::Version.new(Leptris::VERSION) >= Gem::Version.new("1.9.374")
+      # leptris/leptris#1785 fixed the engine root cause: detached
+      # text resolves its owning document, so the mutation succeeds.
+      text.content = "z"
+      expect(text.content).to eq("z")
+    else
+      expect { text.content = "z" }
+        .to raise_error(Moxml::Error, /detached \(parentless\).*issue #401/)
+    end
+  end
+
+  it "keeps created-unattached nodes mutable" do
+    text = ctx.create_document.create_text("x")
+    text.content = "y"
+    expect(text.content).to eq("y")
+  end
+
+  it "keeps attached nodes mutable" do
+    doc = ctx.parse("<r><a>x</a></r>")
+    text = doc.root.children[0].children[0]
+    text.content = "z"
+    expect(text.content).to eq("z")
+  end
+end

data/spec/moxml/adapter/leptris_parse_lint_spec.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Issue #404: Context#parse_html forwards collect_errors (and mode) to
+# the leptris flags entry (leptris#1771's §13.2.5 parse-lint) — the
+# recorded error tokens surface through parse_diagnostics. Face-probed:
+# bindings predating the kwarg skip.
+RSpec.describe "parse_html collect_errors forwarding" do
+  let(:ctx) { Moxml.new(:leptris) }
+  let(:src) { %(<p class="x>unclosed</p><a href=><p>a<b</p>) }
+
+  before do
+    adapter = ctx.config.adapter
+    supported = adapter.singleton_class.const_get(:COLLECT_ERRORS_NATIVE)
+    skip "binding lacks the collect_errors kwarg (leptris#1771)" unless supported
+  end
+
+  it "surfaces parse-lint errors through parse_diagnostics" do
+    doc = ctx.parse_html(src, collect_errors: true)
+    diags = doc.parse_diagnostics
+    expect(diags).not_to be_empty
+    expect(diags.first).to have_key(:message)
+  end
+
+  # Issue #408: the #1771 reader fields ride the diag hash — the
+  # token code and position canon's HtmlValidator maps onto
+  # validation errors (nil where the engine has no token code).
+  it "carries the token code and position (issue #408)" do
+    doc = ctx.parse_html(src, collect_errors: true)
+    eof = doc.parse_diagnostics.find { |d| d[:message].include?("EOF") }
+    expect(eof).not_to be_nil
+    expect(eof[:code]).to eq("eof-in-tag")
+    expect(eof[:line]).to eq(1)
+    expect(eof[:column]).to eq(1)
+  end
+
+  it "keeps the default lane silent (no option, no diagnostics)" do
+    doc = ctx.parse_html(src)
+    expect(doc.parse_diagnostics).to be_empty
+  end
+
+  it "forwards through Context#parse_html options" do
+    doc = ctx.parse_html(src, { collect_errors: true })
+    expect(doc.parse_diagnostics).not_to be_empty
+  end
+end

data/spec/moxml/adapter/shared_examples/adapter_contract.rb

@@ -343,13 +343,13 @@ RSpec.shared_examples "xml adapter" do
     it "respects indentation settings" do
       if described_class.name.include?("Oga") &&
           !described_class.indents_output?
-        pending("Oga does not support indentation settings")
+        pending("D-09: Oga does not support indentation settings")
       end
       if described_class.name.include?("Libxml")
-        skip("LibXML serialization does not support indentation (documented limitation)")
+        skip("D-09: LibXML serialization does not support indentation (documented limitation)")
       end
       if described_class.name.include?("Ox")
-        skip("Ox does not support indentation settings (documented limitation)")
+        skip("D-09: Ox does not support indentation settings (documented limitation)")
       end
 
       unindented = described_class.serialize(doc, indent: 0)

data/spec/moxml/c14n/adapter_delegation_spec.rb

@@ -58,9 +58,9 @@ RSpec.describe "Moxml::C14n cross-adapter canonicalization" do
 
   describe "document-level nodes keep document order" do
     # oga surfaces the XML declaration as a <?xml?> PI and keeps the
-    # separator space in PI content; ox/headed_ox drop PI content on
-    # parse. Both are pre-existing parse-layer divergences, out of
-    # scope here.
+    # separator space in PI content (D-04); ox/headed_ox drop PI
+    # content on parse (D-05). Both are pre-existing parse-layer
+    # divergences, out of scope here.
     let(:adapters) { Moxml::Adapter::AVAILABLE_ADAPTERS - %i[oga ox headed_ox] }
 
     it "canonicalizes a leading PI before the root element" do

data/spec/moxml/c14n/comments_pis_spec.rb

@@ -53,13 +53,13 @@ RSpec.describe "C14N comments and PIs" do
     # PIs, and the DataModel.from_document path drops them. Fixing requires
     # adapter-level work and is tracked separately.
     it "renders PIs outside the document element (KNOWN LIMITATION)" do
-      skip "document-level PI rendering not yet implemented"
+      skip "D-08: document-level PI rendering not yet implemented"
     end
   end
 
   describe "comments at document level" do
     it "renders document-level comments when with_comments: true (KNOWN LIMITATION)" do
-      skip "document-level comment rendering not yet implemented"
+      skip "D-08: document-level comment rendering not yet implemented"
     end
   end
 end

data/spec/moxml/c14n/subset_spec.rb

@@ -63,7 +63,7 @@ RSpec.describe "Moxml::C14n subset canonicalization" do
           next if label == "text selection" && adapter_name == :rexml
 
           # rexml's adapter xpath does not return text nodes for
-          # text() node tests (pre-existing capability gap).
+          # text() node tests (D-07, pre-existing capability gap).
 
           it "canonicalizes #{label}" do
             doc = ctx.parse(xml)
@@ -72,9 +72,9 @@ RSpec.describe "Moxml::C14n subset canonicalization" do
         end
 
         # ox/headed_ox strip comment content padding at the parse
-        # layer (pre-existing, same family as their PI content loss);
-        # only the rendered-comment case depends on it. rexml's
-        # comment() selection gap also only affects this case.
+        # layer (D-06, pre-existing, same family as their PI content
+        # loss); only the rendered-comment case depends on it. rexml's
+        # comment() selection gap (D-07) also only affects this case.
         unless COMMENTS_PADDING_LOSS.include?(adapter_name) ||
             COMMENT_SELECTION_GAP.include?(adapter_name)
           it COMMENTS_CASE[0] do

data/spec/moxml/c14n/w3c_examples_spec.rb

@@ -55,7 +55,8 @@ RSpec.describe "Moxml::C14n W3C REC-xml-c14n examples" do
 
       W3C_FULL_FORMS.each_with_index do |(label, xml, expected), idx|
         # ox/headed_ox strip inter-element whitespace, expand 
-        # and pad comments at parse; oga keeps the PI separator space.
+        # and pad comments at parse (D-05, D-06); oga keeps the PI
+        # separator space (D-04).
         skip_shapes = { ox: [0, CR_SHAPE, PI_SHAPE],
                         headed_ox: [0, CR_SHAPE, PI_SHAPE],
                         oga: [PI_SHAPE] }[adapter_name] || []
@@ -72,6 +73,7 @@ RSpec.describe "Moxml::C14n W3C REC-xml-c14n examples" do
 
   describe "W3C §3 document-subset whitespace" do
     Moxml::Adapter::AVAILABLE_ADAPTERS.each do |adapter_name|
+      # ox/headed_ox strip inter-element whitespace at parse (D-06)
       next if WHITESPACE_SHAPES.include?(adapter_name)
 
       it "renders selected nodes only, whitespace runs in place (#{adapter_name})" do

data/spec/moxml/declaration_preservation_spec.rb

@@ -4,9 +4,9 @@ require "spec_helper"
 
 RSpec.describe "XML Declaration Preservation" do
   # Test with all available adapters
-  ADAPTERS = %i[nokogiri oga rexml ox libxml headed_ox].freeze
+  DECLARATION_SPECS_ADAPTERS = %i[nokogiri oga rexml ox libxml headed_ox].freeze
 
-  ADAPTERS.each do |adapter_name|
+  DECLARATION_SPECS_ADAPTERS.each do |adapter_name|
     context "with #{adapter_name} adapter" do
       let(:context) { Moxml.new(adapter_name) }