rfcxml 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53aebb436f8ea53c627fba3203b2fa9f0186b8f7ac0f4ffd794d2426728172ed
-  data.tar.gz: 7cac09e19781c1bbb31820aaa40bbc7df7f8cb35b7306fbc87496429cf1e7135
+  metadata.gz: d78bc97fa8b73803d80d88b9e3d69d3ab98ea34b481d45b4844b685943cb518e
+  data.tar.gz: 144d9c7c64dc113af0764099683f33bc8eb9f3f3e6ae70077ae51e43d2e2891b
 SHA512:
-  metadata.gz: ea24ee3e3386a8907be82e4a54e6616900b75ec4143ff4bad0e6d79a6d6da8215d7350e778f8f07850156f4789ab010ebc5d0d82533fbaa3a6503496b3a50589
-  data.tar.gz: 3f3a69b7bfd73af3b56fac723256aabcc820c81b572003381ede682f41a0f84535f007465d0368a9644163f930673722f14817800b2e15986eeffcb3529c51c8
+  metadata.gz: 284650ce2accd2ff0a7d75089dd773dce3126e20dcb3a7c02d600612ee4f7bce134b16662e001c2642dedf2d949018550c6d7db6f3781524747ca8aa87b387b9
+  data.tar.gz: cee43215ce256f935a1e7986ca1fdfd30de4ac3f44bdd47caf8a5d34ed7fdc7166bb51a3f7db4d993132868e72aeafe255f2c013491c2ccee29c604abed80afc

data/.github/workflows/roundtrip.yml

@@ -0,0 +1,79 @@
+# GitHub Actions workflow for RFC XML round-trip testing
+# Tests all RFC XML v3 files from rfc-editor.org
+#
+# Issue: https://github.com/metanorma/rfcxml/issues/4
+
+name: RFC Round-Trip Tests
+
+on:
+  # Manual trigger
+  workflow_dispatch:
+  # Weekly run to catch new RFCs (Sundays at 00:00 UTC)
+  schedule:
+    - cron: '0 0 * * 0'
+  # Also run on pushes to main for early detection of issues
+  push:
+    branches: [ main ]
+    paths:
+      - 'lib/**'
+      - 'spec/**'
+      - 'scripts/roundtrip_test.rb'
+  pull_request:
+    paths:
+      - 'lib/**'
+      - 'spec/**'
+      - 'scripts/roundtrip_test.rb'
+
+permissions:
+  contents: read
+
+jobs:
+  roundtrip:
+    name: Test RFC XML Round-Trips
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.2'
+          bundler-cache: true
+
+      - name: Download RFC XML files
+        run: |
+          mkdir -p rfc-xml-source
+          echo "Downloading RFC XML tarball..."
+          curl -L -o xmlsource.tar.gz "https://www.rfc-editor.org/in-notes/tar/xmlsource-all.tar.gz"
+          echo "Extracting..."
+          tar -xzf xmlsource.tar.gz -C rfc-xml-source
+          # The tarball extracts to a subdirectory, find it
+          XML_DIR=$(find rfc-xml-source -name "*.xml" -type f | head -1 | xargs dirname)
+          echo "XML_DIR=$XML_DIR" >> $GITHUB_ENV
+          FILE_COUNT=$(find "$XML_DIR" -name "*.xml" -type f | wc -l)
+          echo "Found $FILE_COUNT XML files in $XML_DIR"
+
+      - name: Run round-trip tests
+        run: |
+          echo "Testing all RFC XML files..."
+          ruby scripts/roundtrip_test.rb "$XML_DIR"
+        continue-on-error: true
+        id: roundtrip
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: roundtrip-results
+          path: |
+            *.log
+          retention-days: 30
+          if-no-files-found: ignore
+
+      - name: Check results
+        if: steps.roundtrip.outcome == 'failure'
+        run: |
+          echo "::error::Some RFC XML files failed round-trip testing"
+          exit 1

data/.gitignore

@@ -7,5 +7,8 @@
 /spec/reports/
 /tmp/
 
+# Downloaded RFC XML files
+/spec/fixtures/xmlsource/
+
 # rspec failure tracking
 .rspec_status

data/.rubocop.yml

@@ -1,11 +1,17 @@
 # Auto-generated by Cimas: Do not edit it manually!
 # See https://github.com/metanorma/cimas
 inherit_from:
+  - https://raw.githubusercontent.com/riboseinc/oss-guides/main/ci/rubocop.yml
   - .rubocop_todo.yml
-  - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
+
+inherit_mode:
+  merge:
+    - Exclude
 
 # local repo-specific modifications
 # ...
+plugins:
+  - rubocop-rspec
+  - rubocop-performance
+  - rubocop-rake
 
-AllCops:
-  TargetRubyVersion: 3.4

data/.rubocop_todo.yml

@@ -1,42 +1,108 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-03-18 06:11:32 UTC using RuboCop version 1.85.1.
+# on 2026-03-19 12:31:01 UTC using RuboCop version 1.85.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
 # Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Gemspec/RequireMFA:
+Gemspec/RequiredRubyVersion:
   Exclude:
     - 'rfcxml.gemspec'
 
-# Offense count: 1
-Gemspec/RequiredRubyVersion:
+# Offense count: 22
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
+# URISchemes: http, https
+Layout/LineLength:
   Exclude:
-    - 'rfcxml.gemspec'
+    - 'canon_attribute_order_bug.rb'
+    - 'lib/rfcxml/v3/li.rb'
+    - 'lib/rfcxml/v3/rfc.rb'
+    - 'scripts/roundtrip_test.rb'
+    - 'spec/v3/document_creation_spec.rb'
+
+# Offense count: 4
+Lint/NoReturnInBeginEndBlocks:
+  Exclude:
+    - 'scripts/roundtrip_test.rb'
+
+# Offense count: 6
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
+Metrics/AbcSize:
+  Exclude:
+    - 'lib/rfcxml/v3/rfc.rb'
+    - 'scripts/roundtrip_test.rb'
+
+# Offense count: 3
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
+# AllowedMethods: refine
+Metrics/BlockLength:
+  Max: 37
+
+# Offense count: 3
+# Configuration parameters: AllowedMethods, AllowedPatterns, Max.
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - 'lib/rfcxml/v3/rfc.rb'
+    - 'scripts/roundtrip_test.rb'
+
+# Offense count: 9
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+Metrics/MethodLength:
+  Max: 50
+
+# Offense count: 3
+# Configuration parameters: AllowedMethods, AllowedPatterns, Max.
+Metrics/PerceivedComplexity:
+  Exclude:
+    - 'lib/rfcxml/v3/rfc.rb'
+    - 'scripts/roundtrip_test.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle.
-# SupportedStyles: normal, indented_internal_methods
-Layout/IndentationConsistency:
+# SupportedStyles: be, be_nil
+RSpec/BeNil:
   Exclude:
-    - 'rfcxml.gemspec'
+    - 'spec/rfcxml_spec.rb'
 
 # Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
-# URISchemes: http, https
-Layout/LineLength:
+# Configuration parameters: IgnoredMetadata.
+RSpec/DescribeClass:
   Exclude:
-    - 'lib/rfcxml/v3/li.rb'
+    - 'spec/v3/document_creation_spec.rb'
 
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
-# SupportedStyles: single_quotes, double_quotes
-Style/StringLiterals:
+# Offense count: 19
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: SkipBlocks, EnforcedStyle, OnlyStaticConstants.
+# SupportedStyles: described_class, explicit
+RSpec/DescribedClass:
   Exclude:
-    - 'rfcxml.gemspec'
+    - 'spec/v3/author_spec.rb'
+    - 'spec/v3/rfc_spec.rb'
+    - 'spec/v3/section_spec.rb'
+
+# Offense count: 11
+# Configuration parameters: CountAsOne.
+RSpec/ExampleLength:
+  Max: 29
+
+# Offense count: 11
+RSpec/MultipleExpectations:
+  Max: 9
+
+# Offense count: 3
+# Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata, InflectorPath, EnforcedInflector.
+# SupportedInflectors: default, active_support
+RSpec/SpecFilePathFormat:
+  Exclude:
+    - 'spec/v3/author_spec.rb'
+    - 'spec/v3/rfc_spec.rb'
+    - 'spec/v3/section_spec.rb'
+
+# Offense count: 1
+Security/Open:
+  Exclude:
+    - 'Rakefile'

data/Gemfile

@@ -5,10 +5,12 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in genericode.gemspec
 gemspec
 
-gem "canon"
+gem "canon", github: "ronaldtse/canon", branch: "fix/empty-attribute-value"
 gem "lutaml-model", github: "lutaml/lutaml-model", ref: "main"
 gem "nokogiri"
 gem "rake", "~> 13.0"
 gem "rspec", "~> 3.0"
 gem "rubocop"
 gem "rubocop-performance"
+gem "rubocop-rake"
+gem "rubocop-rspec"

data/README.adoc

@@ -1,6 +1,7 @@
 = RFC XML Ruby library
 
 The `rfcxml` library is a parser and generator for RFC XML v3 documents.
+
 It provides bidirectional XML serialization using the lutaml-model framework,
 enabling perfect round-trips with namespace preservation.
 
@@ -64,56 +65,153 @@ puts rfc.category        # => "std"
 puts rfc.submission_type # => "IETF"
 
 # Access front matter
-puts rfc.front.title.to_s
+puts rfc.front.title.content
 rfc.front.author.each do |author|
   puts author.fullname
 end
 
 # Access sections
 rfc.middle.section.each do |section|
-  puts section.name
+  puts section.name&.content
 end
 ----
 
-=== Generating RFC XML
+=== Creating an Internet-Draft
+
+Internet-Drafts have a `doc_name` attribute but no `number`:
 
 [source,ruby]
 ----
 require 'rfcxml'
 
-# Create a new RFC document
-rfc = Rfcxml::V3::Rfc.new(
-  number: "1234",
-  category: "info",
-  submission_type: "IETF"
+draft = Rfcxml::V3::Rfc.new(
+  doc_name: "draft-ietf-example-protocol-01",
+  submission_type: "IETF",
+  ipr: "trust200902",
+  category: "std",
+  version: "3",
+
+  front: Rfcxml::V3::Front.new(
+    title: Rfcxml::V3::Title.new(
+      content: "Example Protocol for Testing",
+      abbrev: "Example Protocol"
+    ),
+    author: [
+      Rfcxml::V3::Author.new(
+        fullname: "Jane Doe",
+        initials: "J.",
+        surname: "Doe",
+        role: "editor"
+      )
+    ],
+    date: Rfcxml::V3::Date.new(year: "2025", month: "January")
+  ),
+
+  middle: Rfcxml::V3::Middle.new(
+    section: [
+      Rfcxml::V3::Section.new(
+        anchor: "introduction",
+        name: Rfcxml::V3::Name.new(content: "Introduction"),
+        t: [
+          Rfcxml::V3::Text.new(content: "This is an example Internet-Draft.")
+        ]
+      )
+    ]
+  )
 )
 
-# Build front matter
-rfc.front = Rfcxml::V3::Front.new(
-  title: Rfcxml::V3::Title.new(content: "My RFC Title"),
-  author: [
-    Rfcxml::V3::Author.new(
-      fullname: "John Doe",
-      email: "john@example.com"
-    )
-  ]
-)
+xml = draft.to_xml(pretty: true, declaration: true, encoding: "utf-8")
+----
+
+=== Creating a Published RFC
+
+Published RFCs have a `number` attribute and may have `obsoletes`/`updates`:
+
+[source,ruby]
+----
+require 'rfcxml'
 
-# Build middle section
-rfc.middle = Rfcxml::V3::Middle.new(
-  section: [
-    Rfcxml::V3::Section.new(
-      name: Rfcxml::V3::Name.new(content: "Introduction"),
-      t: [
-        Rfcxml::V3::T.new(content: "This is the introduction.")
-      ]
-    )
-  ]
+rfc = Rfcxml::V3::Rfc.new(
+  number: "9999",
+  category: "std",
+  obsoletes: "9998",
+  updates: "9997,9996",
+  consensus: "true",
+  ipr: "trust200902",
+  version: "3",
+
+  front: Rfcxml::V3::Front.new(
+    title: Rfcxml::V3::Title.new(
+      content: "A Standard Protocol for Example Purposes",
+      abbrev: "Example Standard"
+    ),
+    series_info: [
+      Rfcxml::V3::SeriesInfo.new(name: "RFC", value: "9999", stream: "IETF")
+    ],
+    author: [
+      Rfcxml::V3::Author.new(fullname: "John Smith", surname: "Smith")
+    ],
+    date: Rfcxml::V3::Date.new(year: "2025", month: "March")
+  ),
+
+  middle: Rfcxml::V3::Middle.new(
+    section: [
+      Rfcxml::V3::Section.new(
+        name: Rfcxml::V3::Name.new(content: "Overview"),
+        t: [
+          Rfcxml::V3::Text.new(content: "This document specifies a standard protocol.")
+        ]
+      )
+    ]
+  )
 )
 
-# Serialize to XML
 xml = rfc.to_xml(pretty: true, declaration: true, encoding: "utf-8")
-puts xml
+----
+
+=== Bibliography-Only Usage
+
+If you only need to parse or generate bibliography references (the `<reference>` element),
+you can use `Rfcxml::V3::Reference` directly:
+
+[source,ruby]
+----
+require 'rfcxml'
+
+# Parse a reference from XML
+ref_xml = <<~XML
+  <reference anchor="RFC2119">
+    <front>
+      <title>Key words for use in RFCs to Indicate Requirement Levels</title>
+      <author fullname="S. Bradner" surname="Bradner"/>
+      <date month="March" year="1997"/>
+    </front>
+    <seriesInfo name="RFC" value="2119"/>
+  </reference>
+XML
+
+ref = Rfcxml::V3::Reference.from_xml(ref_xml)
+puts ref.anchor  # => "RFC2119"
+puts ref.front.title.content
+
+# Create a reference programmatically
+ref = Rfcxml::V3::Reference.new(
+  anchor: "RFC8650",
+  front: Rfcxml::V3::Front.new(
+    title: Rfcxml::V3::Title.new(
+      content: "Dynamic Subscription to YANG Events and Datastores over RESTCONF"
+    ),
+    author: [
+      Rfcxml::V3::Author.new(fullname: "E. Voit", surname: "Voit")
+    ],
+    date: Rfcxml::V3::Date.new(year: "2019", month: "September"),
+    series_info: [
+      Rfcxml::V3::SeriesInfo.new(name: "RFC", value: "8650")
+    ]
+  )
+)
+
+xml = ref.to_xml(pretty: true)
 ----
 
 === Round-trip preservation
@@ -152,14 +250,22 @@ The RFC XML v3 structure maps to these Ruby classes:
 | `Rfcxml::V3::Title` | `<title>`
 | `Rfcxml::V3::Author` | `<author>`
 | `Rfcxml::V3::Section` | `<section>`
-| `Rfcxml::V3::T` | `<t>`
-| `Rfcxml::V3::List` | `<ul>`, `<ol>`, `<dl>`
-| `Rfcxml::V3::Figure` | `<figure>`
-| `Rfcxml::V3::Table` | `<table>`
-| `Rfcxml::V3::References` | `<references>`
+| `Rfcxml::V3::Text` | `<t>` (paragraph)
 | `Rfcxml::V3::Reference` | `<reference>`
+| `Rfcxml::V3::References` | `<references>`
 |===
 
+=== Key Differences: Internet-Draft vs Published RFC
+
+| Attribute | Internet-Draft | Published RFC |
+|-----------|----------------|---------------|
+| `doc_name` | Required (e.g., `draft-ietf-wg-topic-01`) | Optional |
+| `number` | Not used | Required (e.g., `"8650"`) |
+| `expires_date` | Optional | Not used |
+| `obsoletes` | Not used | Optional |
+| `updates` | Not used | Optional |
+| `series_info` | Optional | Usually present |
+
 == Serialization Options
 
 The `to_xml` method supports these options:
@@ -185,6 +291,54 @@ xml = rfc.to_xml(
 )
 ----
 
+== Enumeration Validation
+
+The library provides built-in validation for all RFC XML v3 enumeration
+attributes.
+
+These are defined in the v3.rnc schema and implemented using lutaml-model's
+`values:` constraint.
+
+=== Core Document Attributes
+
+|===
+| Attribute | Valid Values | Default
+| `category` | `std`, `bcp`, `exp`, `info`, `historic` | -
+| `consensus` | `no`, `yes`, `false`, `true` | `false`
+| `submissionType` | `IETF`, `IAB`, `IRTF`, `independent`, `editorial` | `IETF`
+| `sortRefs` | `true`, `false` | `false`
+| `symRefs` | `true`, `false` | `true`
+| `tocInclude` | `true`, `false` | `true`
+| `indexInclude` | `true`, `false` | `true`
+|===
+
+=== Section Attributes
+
+|===
+| Attribute | Valid Values | Default
+| `numbered` | `true`, `false` | `true`
+| `toc` | `include`, `exclude`, `default` | `default`
+| `removeInRFC` | `true`, `false` | `false`
+|===
+
+=== Author Attributes
+
+|===
+| Attribute | Valid Values | Default
+| `role` | `editor` | -
+|===
+
+=== Validation
+
+Validation requires an explicit call to `validate` or `validate!`:
+
+[source,ruby]
+----
+rfc = Rfcxml::V3::Rfc.new(category: "invalid")
+errors = rfc.validate  # => array of validation errors
+rfc.validate!          # => raises Lutaml::Model::ValidationError
+----
+
 == Development
 
 After checking out the repo, run:
@@ -202,6 +356,72 @@ This runs tests + linting. To run tests only:
 $ bundle exec rake spec
 ----
 
+=== Round-Trip Testing
+
+The library includes comprehensive round-trip tests that verify XML parsing and
+serialization preserve all document structure. These tests use the
+https://github.com/lutaml/canon[Canon] gem for semantic XML comparison.
+
+==== Downloading RFC XML Fixtures
+
+To run round-trip tests, you need to download RFC XML fixtures from
+rfc-editor.org:
+
+[source]
+----
+$ bundle exec rake rfc:download
+----
+
+This downloads and extracts RFC XML files to `spec/fixtures/xmlsource/`. The
+download is automatically excluded from version control via `.gitignore`.
+
+To re-download fresh fixtures:
+
+[source]
+----
+$ bundle exec rake rfc:redownload
+----
+
+To clean downloaded fixtures:
+
+[source]
+----
+$ bundle exec rake rfc:clean
+----
+
+==== Running Round-Trip Tests
+
+Run round-trip tests for all downloaded RFC XML files:
+
+[source]
+----
+$ bundle exec ruby scripts/roundtrip_test.rb
+----
+
+The test script will:
+
+1. Parse each RFC XML file using `Rfcxml::V3::Rfc.from_xml`
+2. Serialize back to XML using `to_xml`
+3. Compare original and serialized XML using Canon with `spec_friendly` profile
+4. Report pass/fail statistics
+
+Run round-trip tests for specific files:
+
+[source]
+----
+$ bundle exec ruby scripts/roundtrip_test.rb spec/fixtures/xmlsource/rfc8650.xml
+$ bundle exec ruby scripts/roundtrip_test.rb spec/fixtures/xmlsource/rfc8650.xml spec/fixtures/xmlsource/rfc8651.xml
+----
+
+Run round-trip tests with custom thread count:
+
+[source]
+----
+$ bundle exec ruby scripts/roundtrip_test.rb -- --threads 4
+----
+
+Output is saved to `tmp/roundtrip-results-{timestamp}/` with detailed failure reports.
+
 == Architecture
 
 The library uses lutaml-model for XML serialization:

data/Rakefile

@@ -2,6 +2,10 @@
 
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require "open-uri"
+require "rubygems/package"
+require "zlib"
+require "fileutils"
 
 RSpec::Core::RakeTask.new(:spec)
 
@@ -10,3 +14,54 @@ require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
 task default: %i[spec rubocop]
+
+RFC_XML_URL = "https://www.rfc-editor.org/in-notes/tar/xmlsource-all.tar.gz"
+RFC_XML_DIR = File.expand_path("spec/fixtures/xmlsource", __dir__)
+RFC_XML_TAR = File.expand_path("tmp/xmlsource-all.tar.gz", __dir__)
+
+namespace :rfc do
+  desc "Download and extract RFC XML files from rfc-editor.org"
+  task :download do
+    FileUtils.mkdir_p(RFC_XML_DIR)
+    FileUtils.mkdir_p(File.dirname(RFC_XML_TAR))
+
+    # Download tarball if not exists
+    unless File.exist?(RFC_XML_TAR)
+      puts "Downloading RFC XML tarball from #{RFC_XML_URL}..."
+      URI.open(RFC_XML_URL) do |remote|
+        File.binwrite(RFC_XML_TAR, remote.read)
+      end
+      puts "Downloaded to #{RFC_XML_TAR}"
+    end
+
+    # Extract tarball
+    puts "Extracting to #{RFC_XML_DIR}..."
+    tar_extract = Gem::Package::TarReader.new(Zlib::GzipReader.open(RFC_XML_TAR))
+    tar_extract.rewind
+    tar_extract.each do |entry|
+      next unless entry.file? && entry.full_name.end_with?(".xml")
+
+      # Extract only the filename, flatten directory structure
+      filename = File.basename(entry.full_name)
+      target_path = File.join(RFC_XML_DIR, filename)
+
+      File.binwrite(target_path, entry.read)
+    end
+    tar_extract.close
+
+    xml_count = Dir.glob(File.join(RFC_XML_DIR, "*.xml")).count
+    puts "Done! Extracted #{xml_count} XML files to #{RFC_XML_DIR}"
+  end
+
+  desc "Clean downloaded RFC XML files"
+  task :clean do
+    puts "Removing #{RFC_XML_DIR}..."
+    FileUtils.rm_rf(RFC_XML_DIR)
+    puts "Removing #{RFC_XML_TAR}..."
+    FileUtils.rm_f(RFC_XML_TAR)
+    puts "Done!"
+  end
+
+  desc "Re-download RFC XML files (clean + download)"
+  task redownload: %i[clean download]
+end

data/lib/rfcxml/v3/abstract.rb

@@ -13,7 +13,8 @@ module Rfcxml
       attribute :ul, Ul, collection: true
 
       xml do
-        root "abstract"
+        element "abstract"
+        ordered
 
         map_attribute "anchor", to: :anchor
         map_attribute "pn", to: :pn