moxml 0.5.149 → 0.5.151

data/spec/moxml/c14n/subset_spec.rb

@@ -43,9 +43,6 @@ COMMENTS_EXCLUDED_CASE = [
 ].freeze
 
 COMMENTS_PADDING_LOSS = %i[ox headed_ox].freeze
-# rexml's adapter xpath does not return comment()/text() node results
-# (pre-existing capability gap, same family for both axes).
-COMMENT_SELECTION_GAP = %i[rexml].freeze
 
 RSpec.describe "Moxml::C14n subset canonicalization" do
   # Node-set semantics follow the enveloped-signature interop
@@ -60,11 +57,6 @@ RSpec.describe "Moxml::C14n subset canonicalization" do
         let(:ctx) { Moxml.new(adapter_name) }
 
         C14N_SUBSET_CORPUS.each do |label, xml, xpath, expected|
-          next if label == "text selection" && adapter_name == :rexml
-
-          # rexml's adapter xpath does not return text nodes for
-          # text() node tests (D-07, pre-existing capability gap).
-
           it "canonicalizes #{label}" do
             doc = ctx.parse(xml)
             expect(Moxml::C14n.canonicalize_subset(doc, xpath)).to eq(expected)
@@ -73,10 +65,8 @@ RSpec.describe "Moxml::C14n subset canonicalization" do
 
         # ox/headed_ox strip comment content padding at the parse
         # 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)
+        # loss); only the rendered-comment case depends on it.
+        unless COMMENTS_PADDING_LOSS.include?(adapter_name)
           it COMMENTS_CASE[0] do
             doc = ctx.parse(COMMENTS_CASE[1])
             expect(Moxml::C14n.canonicalize_subset(doc, COMMENTS_CASE[2],

data/spec/moxml/c14n/w3c_examples_spec.rb

@@ -13,7 +13,6 @@ require "moxml/c14n"
 # Documented parse-layer divergences (skipped rows):
 # - ox/headed_ox expand 
 to LF, strip inter-element whitespace
 #   and comment padding at parse (out of scope here)
-# - oga keeps the target/content separator space in PI data
 W3C_FULL_FORMS = [
   ["attribute-value whitespace collapses to single spaces",
    "<doc>\n   <e   attr1=\"v1\"\n        attr2   =   \"v2\"\n    >   content   </e>\n</doc>",
@@ -55,11 +54,9 @@ 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 &#xD;
-        # and pad comments at parse (D-05, D-06); oga keeps the PI
-        # separator space (D-04).
+        # and pad comments at parse (D-05, D-06).
         skip_shapes = { ox: [0, CR_SHAPE, PI_SHAPE],
-                        headed_ox: [0, CR_SHAPE, PI_SHAPE],
-                        oga: [PI_SHAPE] }[adapter_name] || []
+                        headed_ox: [0, CR_SHAPE, PI_SHAPE] }[adapter_name] || []
         next if skip_shapes.include?(idx)
 
         it "canonicalizes #{label}" do

data/spec/moxml/element_indent_spec.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Element-level indentation is a declared capability (model, Serialization;
+# D-09): engines that cannot honor the knob raise the named AdapterError
+# instead of answering unindented output. indent: 0 and the no-option
+# path stay common — consumers use them for canonical shapes.
+RSpec.describe "element-level serialization indentation" do
+  it "honors a positive indent on engines that support it" do
+    %i[nokogiri rexml].each do |name|
+      doc = Moxml.new(name).parse("<r><a/></r>")
+      expect(doc.root.to_xml(indent: 2)).to include("\n"),
+                                            "#{name}: indent not honored"
+    end
+  end
+
+  it "raises the named AdapterError on engines that ignore the knob" do
+    %i[oga ox headed_ox libxml leptris].each do |name|
+      doc = Moxml.new(name).parse("<r><a/></r>")
+      expect { doc.root.to_xml(indent: 2) }
+        .to raise_error(Moxml::AdapterError, /indentation/),
+            "#{name}: silent unindented answer"
+    end
+  end
+
+  it "keeps indent: 0 and the no-option path common on every adapter" do
+    Moxml::Adapter::AVAILABLE_ADAPTERS.each do |name|
+      doc = Moxml.new(name).parse("<r><a/></r>")
+      expect(doc.root.to_xml(indent: 0)).to include("<a")
+      expect(doc.root.to_xml).to include("<a")
+    end
+  end
+end

data/spec/moxml/node_spec.rb

@@ -156,9 +156,6 @@ RSpec.describe Moxml::Node do
         end
 
         it "locates the node via its path" do
-          # Ox translates only a limited XPath subset (no positional predicates)
-          skip "D-12: ox xpath translation does not support positional predicates" if adapter_name == :ox
-
           expect(doc.at_xpath(title.path)).to eq(title)
         end
 

data/spec/moxml/relax_ng_spec.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "tempfile"
+
+# RELAX NG facade (TODO.sota/05): engines with an RNG validator
+# answer valid?/validate/validate_errors; engines without one raise
+# the named NotImplementedError at compile and answer supported?
+# without raising.
+RSpec.describe Moxml::RelaxNG do
+  RNG_SCHEMA = <<~RNG # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+    <element name="r" xmlns="http://relaxng.org/ns/structure/1.0">
+      <attribute name="a"><text/></attribute>
+    </element>
+  RNG
+
+  let(:valid_doc) { Moxml.new(:leptris).parse('<r a="x"/>') }
+  let(:invalid_doc) { Moxml.new(:leptris).parse("<r/>") }
+
+  it "answers supported? without raising on every adapter" do
+    Moxml::Adapter::AVAILABLE_ADAPTERS.each do |name|
+      ctx = Moxml.new(name)
+      expect { described_class.supported?(ctx) }.not_to raise_error
+    end
+  end
+
+  it "validates against a compiled schema and reports findings" do
+    ctx = Moxml.new(:leptris)
+    skip "leptris binding has no RNG face" unless described_class.supported?(ctx)
+
+    schema = ctx.relaxng(RNG_SCHEMA)
+    expect(schema.valid?(valid_doc)).to be(true)
+    expect(schema.validate(valid_doc)).to eq([])
+    expect(schema.valid?(invalid_doc)).to be(false)
+    error = schema.validate_errors(invalid_doc).first
+    expect(error[:message]).to include("missing required attribute")
+    expect(error[:line]).to eq(1)
+  end
+
+  it "compiles a schema from a file" do
+    ctx = Moxml.new(:leptris)
+    skip "leptris binding has no RNG face" unless described_class.supported?(ctx)
+
+    Tempfile.create(["schema", ".rng"]) do |file|
+      file.write(RNG_SCHEMA)
+      file.flush
+      schema = ctx.relaxng_file(file.path)
+      expect(schema.valid?(valid_doc)).to be(true)
+      expect(schema.valid?(invalid_doc)).to be(false)
+    end
+  end
+
+  it "raises a named NotImplementedError on engines without an RNG validator" do
+    ctx = Moxml.new(:nokogiri)
+    expect(described_class.supported?(ctx)).to be(false)
+    expect { ctx.relaxng(RNG_SCHEMA) }
+      .to raise_error(Moxml::NotImplementedError, /RELAX NG/)
+  end
+
+  it "names a malformed schema as a ValidationError" do
+    ctx = Moxml.new(:leptris)
+    skip "leptris binding has no RNG face" unless described_class.supported?(ctx)
+
+    expect { ctx.relaxng("<not-a-schema/>") }
+      .to raise_error(Moxml::ValidationError, /RELAX NG/)
+  end
+end

data/spec/moxml/sax_spec.rb

@@ -412,50 +412,39 @@ RSpec.describe Moxml::SAX do
       expect(handler.error_message).to match(/invalid|unclosed|premature|mismatch|not closed/i)
     end
 
-    it "documents CDATA limitation" do
-      # Ox SAX does not have separate CDATA events
-      # All CDATA content is delivered as text() events
-      skip "D-10: Ox SAX does not support separate CDATA events"
-
-      xml_with_cdata = "<root><![CDATA[special content]]></root>"
-
-      cdata_found = false
-      context.sax_parse(xml_with_cdata) do
-        cdata { |_text| cdata_found = true }
-      end
-
-      # This will fail because Ox doesn't support separate CDATA events
-      expect(cdata_found).to be true
+    it "declares CDATA event subscriptions loudly (D-10)" do
+      # Ox SAX has no separate CDATA events; a subscriber gets the
+      # named error rather than an incomplete stream.
+      expect do
+        context.sax_parse("<root><![CDATA[special content]]></root>") do
+          cdata { |_text| nil }
+        end
+      end.to raise_error(Moxml::NotImplementedError, /cdata/)
     end
 
-    it "documents comment limitation" do
-      # Ox SAX does not have separate comment events
-      skip "D-10: Ox SAX does not support separate comment events"
-
-      xml_with_comment = "<root><!-- comment --><data>content</data></root>"
-
-      comment_found = false
-      context.sax_parse(xml_with_comment) do
-        comment { |_text| comment_found = true }
-      end
-
-      # This will fail because Ox doesn't support comment events
-      expect(comment_found).to be true
+    it "declares comment event subscriptions loudly (D-10)" do
+      expect do
+        context.sax_parse("<root><!-- comment --><data>content</data></root>") do
+          comment { |_text| nil }
+        end
+      end.to raise_error(Moxml::NotImplementedError, /comment/)
     end
 
-    it "documents processing instruction limitation" do
-      # Ox SAX does not have separate PI events
-      skip "D-10: Ox SAX does not support separate processing instruction events"
-
-      xml_with_pi = '<?xml-stylesheet type="text/xsl" href="style.xsl"?><root/>'
+    it "declares PI event subscriptions loudly (D-10)" do
+      expect do
+        context.sax_parse('<?xml-stylesheet type="text/xsl" href="style.xsl"?><root/>') do
+          processing_instruction { |_target, _data| nil }
+        end
+      end.to raise_error(Moxml::NotImplementedError, /processing_instruction/)
+    end
 
-      pi_found = false
-      context.sax_parse(xml_with_pi) do
-        processing_instruction { |_target, _data| pi_found = true }
-      end
+    it "declares unsupported families loudly for class handlers too" do
+      handler = Class.new(Moxml::SAX::Handler) do
+        def on_cdata(_text); end
+      end.new
 
-      # This will fail because Ox doesn't support PI events
-      expect(pi_found).to be true
+      expect { context.sax_parse("<root/>", handler) }
+        .to raise_error(Moxml::NotImplementedError, /cdata/)
     end
   end
 
@@ -1024,46 +1013,28 @@ RSpec.describe Moxml::SAX do
       expect(handler.error_message).to match(/invalid|unclosed|premature|mismatch|not closed/i)
     end
 
-    it "documents CDATA limitation (inherited from Ox)" do
-      # HeadedOx inherits Ox's SAX implementation, which does not have separate CDATA events
-      skip "D-10: HeadedOx SAX (inherited from Ox) does not support separate CDATA events"
-
-      xml_with_cdata = "<root><![CDATA[special content]]></root>"
-
-      cdata_found = false
-      context.sax_parse(xml_with_cdata) do
-        cdata { |_text| cdata_found = true }
-      end
-
-      expect(cdata_found).to be true
+    it "declares CDATA event subscriptions loudly (inherited from Ox, D-10)" do
+      expect do
+        context.sax_parse("<root><![CDATA[special content]]></root>") do
+          cdata { |_text| nil }
+        end
+      end.to raise_error(Moxml::NotImplementedError, /cdata/)
     end
 
-    it "documents comment limitation (inherited from Ox)" do
-      # HeadedOx inherits Ox's SAX implementation, which does not have separate comment events
-      skip "D-10: HeadedOx SAX (inherited from Ox) does not support separate comment events"
-
-      xml_with_comment = "<root><!-- comment --><data>content</data></root>"
-
-      comment_found = false
-      context.sax_parse(xml_with_comment) do
-        comment { |_text| comment_found = true }
-      end
-
-      expect(comment_found).to be true
+    it "declares comment event subscriptions loudly (inherited from Ox, D-10)" do
+      expect do
+        context.sax_parse("<root><!-- comment --><data>content</data></root>") do
+          comment { |_text| nil }
+        end
+      end.to raise_error(Moxml::NotImplementedError, /comment/)
     end
 
-    it "documents processing instruction limitation (inherited from Ox)" do
-      # HeadedOx inherits Ox's SAX implementation, which does not have separate PI events
-      skip "D-10: HeadedOx SAX (inherited from Ox) does not support separate processing instruction events"
-
-      xml_with_pi = '<?xml-stylesheet type="text/xsl" href="style.xsl"?><root/>'
-
-      pi_found = false
-      context.sax_parse(xml_with_pi) do
-        processing_instruction { |_target, _data| pi_found = true }
-      end
-
-      expect(pi_found).to be true
+    it "declares PI event subscriptions loudly (inherited from Ox, D-10)" do
+      expect do
+        context.sax_parse('<?xml-stylesheet type="text/xsl" href="style.xsl"?><root/>') do
+          processing_instruction { |_target, _data| nil }
+        end
+      end.to raise_error(Moxml::NotImplementedError, /processing_instruction/)
     end
   end
 end

data/spec/moxml/xpath_capabilities_spec.rb

@@ -81,9 +81,7 @@ RSpec.describe "XPath Capabilities" do
         it "supports attribute value matching ([@attr='value'])" do
           doc = Moxml.new.parse(simple_xml)
           programming = doc.xpath("//book[@category='programming']")
-          expect(programming.length).to be >= 0 # May not work on all
-        rescue Moxml::XPathError
-          skip "D-12: Attribute value predicates not supported on #{adapter_name}"
+          expect(programming.length).to eq(1)
         end
       end
 
@@ -96,9 +94,7 @@ RSpec.describe "XPath Capabilities" do
           }
 
           items = doc.xpath("//book:item", namespaces)
-          expect(items.length).to be >= 0
-        rescue Moxml::XPathError, NoMethodError
-          skip "D-12: Namespace XPath not supported on #{adapter_name}"
+          expect(items.length).to eq(2)
         end
 
         it "handles default namespaces" do
@@ -106,9 +102,7 @@ RSpec.describe "XPath Capabilities" do
           namespaces = { "lib" => "http://library.org" }
 
           library = doc.xpath("//lib:library", namespaces)
-          expect(library.length).to be >= 0
-        rescue Moxml::XPathError, NoMethodError
-          skip "D-12: Default namespace XPath not supported on #{adapter_name}"
+          expect(library.length).to eq(1)
         end
       end
 
@@ -116,17 +110,13 @@ RSpec.describe "XPath Capabilities" do
         it "supports numeric positions ([1])" do
           doc = Moxml.new.parse(simple_xml)
           first_book = doc.xpath("//book[1]")
-          expect(first_book.length).to be >= 0
-        rescue Moxml::XPathError
-          skip "D-12: Position predicates not supported on #{adapter_name}"
+          expect(first_book.length).to eq(1)
         end
 
         it "supports position() function" do
           doc = Moxml.new.parse(simple_xml)
           first_books = doc.xpath("//book[position()=1]")
-          expect(first_books.length).to be >= 0
-        rescue Moxml::XPathError
-          skip "D-12: position() function not supported on #{adapter_name}"
+          expect(first_books.length).to eq(1)
         end
       end
 
@@ -134,20 +124,13 @@ RSpec.describe "XPath Capabilities" do
         it "supports count() function, returning the scalar unwrapped" do
           doc = Moxml.new.parse(simple_xml)
           result = doc.xpath("count(//book)")
-          # REXML's XPath has no function support and yields an empty set
-          skip "D-12: count() function not supported on #{adapter_name}" if result.is_a?(Moxml::NodeSet)
-
           expect(result).to eq(2)
-        rescue Moxml::XPathError, NoMethodError
-          skip "D-12: count() function not supported on #{adapter_name}"
         end
 
         it "supports text() node selection" do
           doc = Moxml.new.parse(simple_xml)
           texts = doc.xpath("//title/text()")
-          expect(texts.length).to be >= 0
-        rescue Moxml::XPathError
-          skip "D-12: text() not supported on #{adapter_name}"
+          expect(texts.length).to eq(3)
         end
       end
 
@@ -155,17 +138,13 @@ RSpec.describe "XPath Capabilities" do
         it "supports numeric comparisons ([@attr < value])" do
           doc = Moxml.new.parse(simple_xml)
           cheap_books = doc.xpath("//book[@id < 2]")
-          expect(cheap_books.length).to be >= 0
-        rescue Moxml::XPathError
-          skip "D-12: Numeric predicates not supported on #{adapter_name}"
+          expect(cheap_books.length).to eq(1)
         end
 
         it "supports boolean expressions ([cond1 and cond2])" do
           doc = Moxml.new.parse(simple_xml)
           result = doc.xpath("//book[@id and @category]")
-          expect(result.length).to be >= 0
-        rescue Moxml::XPathError
-          skip "D-12: Boolean expressions not supported on #{adapter_name}"
+          expect(result.length).to eq(2)
         end
       end
 
@@ -173,17 +152,13 @@ RSpec.describe "XPath Capabilities" do
         it "supports child axis" do
           doc = Moxml.new.parse(simple_xml)
           children = doc.xpath("/library/child::book")
-          expect(children.length).to be >= 0
-        rescue Moxml::XPathError
-          skip "D-12: child:: axis not supported on #{adapter_name}"
+          expect(children.length).to eq(2)
         end
 
         it "supports descendant axis" do
           doc = Moxml.new.parse(simple_xml)
           descendants = doc.xpath("//library/descendant::title")
-          expect(descendants.length).to be >= 0
-        rescue Moxml::XPathError
-          skip "D-12: descendant:: axis not supported on #{adapter_name}"
+          expect(descendants.length).to eq(3)
         end
       end
 
@@ -191,9 +166,7 @@ RSpec.describe "XPath Capabilities" do
         it "supports union (|)" do
           doc = Moxml.new.parse(simple_xml)
           items = doc.xpath("//book | //magazine")
-          expect(items.length).to be >= 0
-        rescue Moxml::XPathError
-          skip "D-12: Union operator not supported on #{adapter_name}"
+          expect(items.length).to eq(3)
         end
       end
     end

data/spec/support/input_taxonomy.rb

@@ -67,6 +67,10 @@ module InputTaxonomy
       text: { oga: "D-14" },
       pi_content: { ox: "D-05", headed_ox: "D-05" },
     },
+    "pi/comment/cdata: pi trailing whitespace" => {
+      text: { oga: "D-14" },
+      pi_content: { ox: "D-05", headed_ox: "D-05", rexml: "D-20" },
+    },
     "huge text with entities" => {
       text: { rexml: "D-16" },
       serialize: { rexml: "D-16" },
@@ -191,6 +195,9 @@ module InputTaxonomy
       Input.new("pi/comment/cdata: pi multi-space separator", "pi/comment/cdata edges",
                 "<r><?pi   data?></r>", true,
                 "separator whitespace is not PI content (uniform)"),
+      Input.new("pi/comment/cdata: pi trailing whitespace", "pi/comment/cdata edges",
+                "<r><?pi data   ?></r>", true,
+                "trailing whitespace is PI data (D-20 on rexml)"),
       Input.new("pi/comment/cdata: empty pi", "pi/comment/cdata edges",
                 "<r><?pi?></r>", true, nil),
 

data/spec/support/model_coverage.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+# The model-coverage matrix (TODO.sota/01, TODO.sota/07): every face
+# family of the processing model mapped to the normative section it
+# cites, the pin that enforces it, and per-adapter dispositions
+# (registered divergence or named loud error). One source of truth for
+# the audit, the model-document pin lists, and the published coverage
+# page.
+module ModelCoverage
+  MODEL_COVERAGE_MATRIX = {
+    "document order and children listing" => {
+      section: "Document order and traversal",
+      pin: "spec/consistency/adapter_parity_spec.rb",
+    },
+    "name resolution" => {
+      section: "Names and namespaces",
+      pin: "spec/consistency/xpath_idioms_spec.rb",
+    },
+    "namespace resolution and bindings normalization" => {
+      section: "Names and namespaces",
+      pin: "spec/consistency/xpath_idioms_spec.rb",
+    },
+    "attribute access" => {
+      section: "Access semantics",
+      pin: "spec/moxml/attribute_resolver_spec.rb",
+    },
+    "text/content/raw_content" => {
+      section: "Access semantics",
+      pin: "spec/moxml/text_spec.rb",
+    },
+    "parsing modes and diagnostics" => {
+      section: "Parsing",
+      pin: "spec/moxml/document_parse_diagnostics_spec.rb",
+    },
+    "EOL normalization" => {
+      section: "Parsing",
+      pin: "spec/consistency/eol_normalization_spec.rb",
+      exempt: { oga: "D-02", ox: "D-03" },
+    },
+    "entity modes" => {
+      section: "Parsing",
+      pin: "spec/moxml/entity_spec.rb",
+    },
+    "XPath evaluation and declared idioms" => {
+      section: "XPath evaluation",
+      pin: "spec/consistency/xpath_idioms_spec.rb",
+    },
+    "serialization shapes (xml/html/xhtml)" => {
+      section: "Serialization",
+      pin: "spec/moxml/xhtml_output_spec.rb",
+    },
+    "indentation knobs" => {
+      section: "Serialization",
+      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" => {
+      section: "Canonicalization",
+      pin: "spec/moxml/c14n/adapter_delegation_spec.rb",
+      exempt: { ox: "D-05", headed_ox: "D-05" },
+    },
+    "XSLT" => {
+      section: "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" => {
+      section: "SAX",
+      pin: "spec/moxml/sax_spec.rb",
+    },
+    "materialization" => {
+      section: "Materialization",
+      pin: "spec/moxml/plan_conformance_spec.rb",
+    },
+    "loud capability contracts" => {
+      section: "Errors and loud degradation",
+      pin: "spec/consistency/loud_degradation_spec.rb",
+    },
+  }.freeze
+
+  # Normative sections that are not face families (meta/apparatus).
+  MODEL_COVERAGE_NON_FACE = [
+    "Status and precedence",
+    "Mission and invariant",
+    "Object model",
+    "Performance: a declared, non-semantic channel",
+  ].freeze
+
+  MODEL_COVERAGE_ADAPTERS = %i[nokogiri oga rexml ox headed_ox libxml leptris].freeze
+
+  module_function
+
+  def families
+    MODEL_COVERAGE_MATRIX.keys
+  end
+
+  def sections
+    MODEL_COVERAGE_MATRIX.values.map { |cell| cell[:section] }.uniq
+  end
+
+  def pins_for(section)
+    MODEL_COVERAGE_MATRIX.values.select { |cell| cell[:section] == section }
+      .filter_map { |cell| cell[:pin] }.uniq.sort
+  end
+
+  def disposition(family, adapter)
+    cell = MODEL_COVERAGE_MATRIX.fetch(family)
+    if (id = (cell[:exempt] || {})[adapter])
+      [:specd, id]
+    elsif (error = (cell[:loud] || {})[adapter])
+      [:loud, error]
+    else
+      [:equivalent, nil]
+    end
+  end
+
+  def cell_text(family, adapter)
+    kind, detail = disposition(family, adapter)
+    case kind
+    when :specd then detail
+    when :loud then "loud (#{detail.split('::').last})"
+    else "equivalent"
+    end
+  end
+
+  # The published page block, deterministic (no clock, no engine
+  # versions): the page is a view of the committed matrix and register,
+  # so a data change without regeneration fails CI.
+  def render_page_block
+    lines = []
+    lines << "Generated by `bundle exec rake docs:coverage` from the " \
+             "coverage matrix and the divergence register. Do not edit " \
+             "by hand: `spec/consistency/published_docs_spec.rb` fails " \
+             "when this block is stale."
+    lines << ""
+    lines << %([cols="4#{',1' * MODEL_COVERAGE_ADAPTERS.size}",options="header"])
+    lines << "|==="
+    lines << "| Face family | " \
+             "#{MODEL_COVERAGE_ADAPTERS.map { |adapter| adapter.to_s.tr('_', ' ') }.join(' | ')}"
+    families.each do |family|
+      lines << "| #{family} | " \
+               "#{MODEL_COVERAGE_ADAPTERS.map { |adapter| cell_text(family, adapter) }.join(' | ')}"
+    end
+    lines << "|==="
+    lines << ""
+    lines << "*equivalent* — all adapters answer the same observable " \
+             "result. *loud (...)* — the adapter raises the named error " \
+             "for that face. *D-NN* — a registered divergence in " \
+             "link:divergences.html[the register], with its rationale. " \
+             "Every cell cites a pin; see the processing model's " \
+             "`Pins::` line for the enforcing specs."
+    lines.join("\n")
+  end
+end