rfcxml 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b11cbfa392f124f60b2e407491746679edd9adce04e41efc4a93e57dc00b958
-  data.tar.gz: a613b687d3808dc83d7b75840129b2e594041e7a8c811adda836aa0b547af501
+  metadata.gz: d78bc97fa8b73803d80d88b9e3d69d3ab98ea34b481d45b4844b685943cb518e
+  data.tar.gz: 144d9c7c64dc113af0764099683f33bc8eb9f3f3e6ae70077ae51e43d2e2891b
 SHA512:
-  metadata.gz: 5f499a434f14334a0a4a85c036426e4ff4444007393fbe5815a07c7f73e0e504df84d43ade669bebd7aa8dd89922c8177fd0fd1c985dec9a05c031648533c16c
-  data.tar.gz: 2e36d85702ec42c68e4c5b4fd0d9393e59b0ad6baef6952e299b0b53bb934b5f647242a2baefce7b3f3380b7cdbef073cca6740b0f4fda2acb9387c45ab5515b
+  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,38 +1,108 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-01-11 09:55:13 UTC using RuboCop version 1.70.0.
+# 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
-# Configuration parameters: Severity, Include.
-# Include: **/*.gemspec
 Gemspec/RequiredRubyVersion:
   Exclude:
     - 'rfcxml.gemspec'
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: with_first_element, with_fixed_indentation
-Layout/ArrayAlignment:
-  Exclude:
-    - 'lib/rfcxml/v3/dt.rb'
-
-# Offense count: 2
+# Offense count: 22
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Max, AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
+# Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Exclude:
-    - 'lib/rfcxml/v3/dt.rb'
+    - '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: AllowInHeredoc.
-Layout/TrailingWhitespace:
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: be, be_nil
+RSpec/BeNil:
+  Exclude:
+    - 'spec/rfcxml_spec.rb'
+
+# Offense count: 1
+# Configuration parameters: IgnoredMetadata.
+RSpec/DescribeClass:
+  Exclude:
+    - 'spec/v3/document_creation_spec.rb'
+
+# Offense count: 19
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: SkipBlocks, EnforcedStyle, OnlyStaticConstants.
+# SupportedStyles: described_class, explicit
+RSpec/DescribedClass:
+  Exclude:
+    - '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:
-    - 'lib/rfcxml/v3/dt.rb'
+    - 'Rakefile'

data/Gemfile

@@ -5,10 +5,12 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in genericode.gemspec
 gemspec
 
-gem "equivalent-xml"
+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 "xml-c14n"
+gem "rubocop-rake"
+gem "rubocop-rspec"

data/README.adoc

@@ -1,8 +1,28 @@
 = RFC XML Ruby library
 
-The `rfcxml` library is a parser and generator for RFC XML documents. It is
-intended to be used to parse and generate RFC XML v3 documents.
+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.
+
+== Features
+
+- Parse RFC XML v3 documents into Ruby objects
+- Generate RFC XML v3 documents from Ruby objects
+- Perfect round-trip preservation (namespaces, `xml:lang`, etc.)
+- Full support for all RFC XML v3 elements
+- Built on lutaml-model for declarative XML mapping
+
+== Requirements
+
+- Ruby >= 3.2.0
+- lutaml-model ~> 0.8.0 (required for namespace preservation and `xml:lang` support)
+
+The lutaml-model 0.8.0 dependency provides:
+
+- Automatic namespace declaration preservation (`xmlns:*` attributes)
+- Built-in `Lutaml::Xml::W3c::XmlLangType` for `xml:lang` attribute handling
+- Perfect XML round-trip support
 
 == Installation
 
@@ -27,47 +47,395 @@ Or install it yourself as:
 $ gem install rfcxml
 ----
 
+== Usage
 
+=== Parsing an RFC XML document
 
-== Usage
+[source,ruby]
+----
+require 'rfcxml'
+
+# Parse from file
+xml = File.read('rfc8650.xml')
+rfc = Rfcxml::V3::Rfc.from_xml(xml)
+
+# Access document attributes
+puts rfc.number           # => "8650"
+puts rfc.category        # => "std"
+puts rfc.submission_type # => "IETF"
+
+# Access front matter
+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&.content
+end
+----
 
-To parse an RFC XML document:
+=== Creating an Internet-Draft
+
+Internet-Drafts have a `doc_name` attribute but no `number`:
+
+[source,ruby]
+----
+require 'rfcxml'
+
+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.")
+        ]
+      )
+    ]
+  )
+)
+
+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'
 
-rfc = Rfcxml::Document.new(File.read('rfc.xml'))
-puts rfc.title
-puts rfc.abstract
-puts rfc.sections
+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.")
+        ]
+      )
+    ]
+  )
+)
+
+xml = rfc.to_xml(pretty: true, declaration: true, encoding: "utf-8")
 ----
 
-To generate an RFC XML document:
+=== 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'
 
-rfc = Rfcxml::Document.new
-rfc.title = 'An RFC Title'
-rfc.abstract = 'An RFC Abstract'
-rfc.sections = [
-  Rfcxml::Section.new('Section 1', 'This is the first section'),
-  Rfcxml::Section.new('Section 2', 'This is the second section')
-]
+# 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
+
+The library preserves all XML structure during round-trips:
+
+[source,ruby]
+----
+require 'rfcxml'
+
+# Parse
+input = File.read('rfc.xml')
+rfc = Rfcxml::V3::Rfc.from_xml(input)
+
+# Serialize back
+output = rfc.to_xml(pretty: true, declaration: true, encoding: "utf-8")
+
+# The output preserves:
+# - xml:lang attribute
+# - xmlns:* namespace declarations (e.g., xmlns:xi for XInclude)
+# - All element structure and content
+----
+
+== Document Structure
+
+The RFC XML v3 structure maps to these Ruby classes:
+
+[cols="2,3"]
+|===
+| Ruby Class | XML Element
+
+| `Rfcxml::V3::Rfc` | `<rfc>` (root)
+| `Rfcxml::V3::Front` | `<front>`
+| `Rfcxml::V3::Middle` | `<middle>`
+| `Rfcxml::V3::Back` | `<back>`
+| `Rfcxml::V3::Title` | `<title>`
+| `Rfcxml::V3::Author` | `<author>`
+| `Rfcxml::V3::Section` | `<section>`
+| `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:
+
+[cols="1,1,3"]
+|===
+| Option | Default | Description
+
+| `:pretty` | `false` | Pretty-print XML with indentation
+| `:declaration` | `false` | Include XML declaration
+| `:encoding` | `"utf-8"` | Set encoding in XML declaration
+| `:omit_doctype` | `false` | Omit DOCTYPE declaration
+|===
+
+Example:
+
+[source,ruby]
+----
+xml = rfc.to_xml(
+  pretty: true,
+  declaration: true,
+  encoding: "utf-8"
+)
+----
+
+== Enumeration Validation
+
+The library provides built-in validation for all RFC XML v3 enumeration
+attributes.
 
-puts rfc.to_xml
+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:
+
+[source]
 ----
+$ bundle install
+$ bundle exec rake
+----
+
+This runs tests + linting. To run tests only:
+
+[source]
+----
+$ 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:
+
+- All elements inherit from `Lutaml::Model::Serializable`
+- Attributes are declared with `attribute` class method
+- XML mapping is defined in `xml do ... end` block
+- Circular references use string class names (e.g., `"Rfcxml::V3::Section"`)
 
 == Contributing
 
 Bug reports and pull requests are welcome on GitHub at
 https://github.com/metanorma/rfcxml.
 
-
 == Copyright and license
 
 The gem is available as open source under the terms of the BSD 2-clause license.