relaton-un 1.20.1 → 2.0.0.pre.alpha.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6560e3649781f334dc28f9c4e5d7e7781bead476afe352e82e2c3b4585559cff
-  data.tar.gz: ee9a9eb72db2871de51ef08bde79314c927360c5cd52f368341f2f966ea651f2
+  metadata.gz: d329d6b49f77f6a2fd2a1ed6b1ccc1204074e5f9415d948de9352361af97cb7b
+  data.tar.gz: 64946c2287d40673e5fbd186c542f9a7e47cf53c0082c0a62f6f150e7af63e80
 SHA512:
-  metadata.gz: f23749670c7895c400f9a26d53820f47b0c557a40865936085d41baef7c98564c019e4c9a89a5a25b96e03cac2510798d4a6c6ca03ce56f9571ca07696202b02
-  data.tar.gz: 5501430f6b938e2dbb824e83f7d678200ba0c91c97bcd94335932060b43edf32d5febfc4c8fe62b9b861a21dd3a400fc4501a01de8ed619a765f999a3b08a91e
+  metadata.gz: 485f49c382375e5b4b91775562d62e456b5a9066eb4d728eb8c018b9121fd94c768cfa8f8f4bc7cdfb315f1e78a9d7eafa610f29ecec1f1b711258603dd1ad18
+  data.tar.gz: dbb0cb1629ab456306d0746602e687c3d977b20eadb55331c523ccc7207ee72ed2af4bbe803bf413b39e79b053c7ccccdcb4c203d061d2c57731d99f0880a18a

data/.github/workflows/rake.yml

@@ -7,6 +7,7 @@ on:
     branches: [ master, main ]
     tags: [ v* ]
   pull_request:
+  workflow_dispatch:
 
 jobs:
   rake:

data/.gitignore

@@ -14,3 +14,4 @@
 .vscode/
 .byebug_history
 Gemfile.lock
+.claude/

data/.rubocop.yml

@@ -7,6 +7,6 @@ require: rubocop-rails
 inherit_from:
   - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
 AllCops:
-  TargetRubyVersion: 2.7
+  TargetRubyVersion: 3.2
 Rails:
   Enabled: false

data/CLAUDE.md

@@ -0,0 +1,77 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+relaton-un is a Ruby gem that provides bibliographic data models for UN documents, part of the Relaton family of gems. It extends `relaton-bib` with UN-specific metadata using the LutaML-Model serialization framework. Currently on the `lutaml-integration` branch undergoing a major migration from the old `RelatonUn` namespace to `Relaton::Un`.
+
+## Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run all tests (also the default rake task)
+bundle exec rake spec
+
+# Run a specific test file
+bundle exec rspec spec/relaton/un/bibitem_spec.rb
+
+# Run a specific test by line number
+bundle exec rspec spec/relaton/un/bibitem_spec.rb:7
+
+# Lint
+bundle exec rubocop
+
+# Interactive console with gem loaded
+bin/console
+```
+
+## Architecture
+
+### Flavor Model Pattern
+
+The gem follows the Relaton flavor pattern: base classes from `relaton-bib` (`Bib::Item`) are extended with a flavor-specific `Ext` class containing UN-specific metadata.
+
+```
+Bib::ItemData (from relaton-bib)
+  └── Relaton::Un::ItemData    # UN flavor identity, enables NamespaceHelper#namespace → Relaton::Un
+
+Bib::Item (from relaton-bib)
+  └── Relaton::Un::Item        # model ItemData; adds Ext attribute
+        ├── Relaton::Un::Bibitem   # includes Bib::BibitemShared (for <bibitem> XML)
+        └── Relaton::Un::Bibdata   # includes Bib::BibdataShared (for <bibdata> XML)
+```
+
+### Key Classes (all in `lib/relaton/un/`)
+
+- **ItemData** — extends `Bib::ItemData`; the UN-specific data container used by `Item` via `model ItemData`
+- **Item** — extends `Bib::Item`, adds `ext` attribute of type `Ext`
+- **Bibitem / Bibdata** — extend Item with shared mixins for two XML serialization formats
+- **Ext** — UN-specific metadata: `doctype`, `distribution`, `session`, `submissionlanguage`, `job_number`; extends `Bib::Ext`
+- **Session** — session metadata (number, date, item numbers/names, collaborator, agenda_id)
+- **Doctype** — restricts document types to: recommendation, plenary, addendum, communication, corrigendum, reissue, agenda, budgetary, sec-gen-notes, expert-report, resolution
+
+### LutaML-Model Serialization
+
+All model classes use `Lutaml::Model::Serializable`. XML mappings are defined in `xml do` blocks:
+- `map_attribute` for XML attributes (e.g., `schema-version` → `schema_version`)
+- `map_element` for XML elements (e.g., `session-date` → `session_date`)
+- `collection: true` for array attributes
+- `values: [...]` for restricted string values
+
+### Schema Validation
+
+RelaxNG grammars in `grammars/` validate XML output. The compiled schema is `grammars/relaton-un-compile.rng`. Tests use `ruby-jing` for validation.
+
+### Testing Approach
+
+Tests are round-trip serialization tests: load a fixture, serialize to XML/YAML, compare against the original fixture. Bibitem and Bibdata specs also validate XML against the RelaxNG schema. Fixtures live in `spec/fixtures/`.
+
+## Dependencies
+
+- **relaton-bib** (~> 2.0.0-alpha.1) — base bibliographic model with LutaML-Model integration
+- **faraday** — HTTP client
+- **ruby-jing** (dev) — RelaxNG schema validation in tests
+- **equivalent-xml** (dev) — XML comparison in tests

data/README.adoc

@@ -1,8 +1,8 @@
 = Relaton for UN documents
 
-RelatonCalconnect is a Ruby gem that implements the https://github.com/metanorma/metanorma-model-iso#iso-bibliographic-item[IsoBibliographicItem model].
+RelatonUn is a Ruby gem that implements the https://github.com/metanorma/metanorma-model-iso#iso-bibliographic-item[IsoBibliographicItem model].
 
-You can use it to retrieve metadata of Calconnect Standards from https://standards.calconnect.org, and access such metadata through the `CcBibliographicItem` object.
+You can use it to retrieve metadata of UN documents from https://documents.un.org, and access such metadata through the `Relaton::Un::Item` object.
 
 == Installation
 
@@ -27,14 +27,14 @@ Or install it yourself as:
 
 [source,ruby]
 ----
-require 'relaton_un'
+require 'relaton/un'
 => true
 
-hits = RelatonUn::UnBibliography.search("TRADE/CEFACT/2004/32")
-=> <RelatonUn::HitCollection:0x007fc4e6ec2018 @ref=TRADE/CEFACT/2004/32 @fetched=false>
+hits = Relaton::Un::Bibliography.search("TRADE/CEFACT/2004/32")
+=> <Relaton::Un::HitCollection:0x00000000001660 @ref=TRADE/CEFACT/2004/32 @fetched=false>
 
-item = hits[0].fetch
-=> #<RelatonUn::UnBibliographicItem:0x007fc4e6ac3138
+item = hits[0].item
+=> #<Relaton::Un::Item:0x000000012385aa60
 ...
 ----
 
@@ -43,24 +43,43 @@ item = hits[0].fetch
 [source,ruby]
 ----
 item.to_xml
-=> "<bibitem id="TRADE-CEFACT-2004-32" type="standard" schema-version="v1.2.1">
-      <fetched>2022-12-05</fetched>
-      ...
+=> "<bibitem id="TRADECEFACT200432" type="standard" schema-version="v1.4.1">
+      <fetched>2026-03-03</fetched>
+      <title language="en" script="Latn" type="title-main"/>
+      <title language="en" script="Latn" type="main"/>
+      <uri type="pdf">https://documents.un.org/api/symbol/access?j=G0430683&amp;t=pdf</uri>
+      <docidentifier type="UN" primary="true">TRADE/CEFACT/2004/32</docidentifier>
+      <docnumber>TRADE/CEFACT/2004/32</docnumber>
+      <date type="published">
+        <on>2004-03-18</on>
+      </date>
+      <language>en</language>
+      <script>Latn</script>
     </bibitem>"
 ----
 With argument `bibdata: true` it outputs XML wrapped by `bibdata` element and adds flavor `ext` element.
 [source,ruby]
 ----
 item.to_xml bibdata: true
-=> "<bibdata type="standard" schema-version="v1.2.1">
-      <fetched>2022-12-05</fetched>
-      ...
+=> "<bibdata type="standard" schema-version="v1.4.1">
+      <fetched>2026-03-03</fetched>
+      <title language="en" script="Latn" type="title-main"/>
+      <title language="en" script="Latn" type="main"/>
+      <uri type="pdf">https://documents.un.org/api/symbol/access?j=G0430683&amp;t=pdf</uri>
+      <docidentifier type="UN" primary="true">TRADE/CEFACT/2004/32</docidentifier>
+      <docnumber>TRADE/CEFACT/2004/32</docnumber>
+      <date type="published">
+        <on>2004-03-18</on>
+      </date>
+      <language>en</language>
+      <script>Latn</script>
       <ext schema-version="v1.0.0">
-        <editorialgroup>
-          <committee>Committee on Trade</committee>
-          <committee>Centre for Trade Facilitation and Electronic Business</committee>
-        </editorialgroup>
-        ...
+        <distribution>general</distribution>
+        <session>
+          <number>10</number>
+          <agenda-id>12</agenda-id>
+        </session>
+        <job_number>G0430683</job_number>
       </ext>
     </bibdata>"
 ----
@@ -68,46 +87,39 @@ item.to_xml bibdata: true
 === Get code, and year
 [source,ruby]
 ----
-RelatonUn::UnBibliography.get "UN TRADE/CEFACT/2004/32"
-[relaton-un] (UN TRADE/CEFACT/2004/32) Fetching from documents.un.org ...
-[relaton-un] (UN TRADE/CEFACT/2004/32) Found: `TRADE/CEFACT/2004/32`
-=> #<RelatonUn::UnBibliographicItem:0x007fdc5f1c3a20
+Relaton::Un::Bibliography.get "UN TRADE/CEFACT/2004/32"
+[relaton-un] INFO: (UN TRADE/CEFACT/2004/32) Fetching from documents.un.org ...
+[relaton-un] INFO: (UN TRADE/CEFACT/2004/32) Found: `TRADE/CEFACT/2004/32`
+=> #<Relaton::Un::ItemData:0x0000000127d9c448
 ...
 ----
 
 === Typed links
 
-UN documens may have `pdf` and `word` link types.
+UN documens may have `pdf` and `word` source link types.
 
 [source,ruby]
 ----
-item.link
-=> [#<RelatonBib::TypedUri:0x00007f81af368250
-  @content=#<Addressable::URI:0x9ec URI:https://documents-dds-ny.un.org/doc/UNDOC/GEN/G04/306/83/pdf/G0430683.pdf?OpenElement>, @type="pdf">,
- #<RelatonBib::TypedUri:0x00007f81af3630e8 @content=#<Addressable::URI:0xa00 URI:https://documents-dds-ny.un.org/doc/UNDOC/GEN/G04/306/83/doc/G0430683.DOC?OpenElement>, @type="word">]
+item.source[0].type
+=> "pdf"
+
+item.source[0].content
+=> "https://documents.un.org/api/symbol/access?j=G0430683&t=pdf"
 ----
 
 === Create bibliographic item from XML
 [source,ruby]
 ----
-RelatonUn::XMLParser.from_xml File.read('spec/fixtures/un_bib.xml')
-=> #<RelatonUn::UnBibliographicItem:0x007fdc5e7ab678
+Relaton::Un::Bibdata.from_xml File.read('spec/fixtures/bibdata.xml')
+=> #<Relaton::Bib::ItemData:0x000000012772a448
 ...
 ----
 
 === Create bibliographic item from YAML
 [source,ruby]
 ----
-hash = YAML.load_file 'spec/fixtures/un_bib.yaml'
-=> {"id"=>"TRADE/CEFACT/2004/32",
-...
-
-bib_hash = RelatonUn::HashConverter.hash_to_bib hash
-=> {:id=>"TRADE/CEFACT/2004/32",
-...
-
-RelatonUn::UnBibliographicItem.new **bib_hash
-=> #<RelatonUn::UnBibliographicItem:0x007fdc5e061908
+Relaton::Un::Item.from_yaml File.read('spec/fixtures/item.yaml')
+=> #<Relaton::Un::ItemData:0x0000000127d7a140
 ...
 ----