relaton 3.0.0.pre.alpha.16 → 3.0.0.pre.alpha.18

data/lib/relaton/easc/CLAUDE.md

@@ -0,0 +1,85 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with
+the EASC flavor. It is a dev doc — excluded from the packaged gem via the
+gemspec `files` glob.
+
+## What this flavor is
+
+`Relaton::Easc` retrieves **EASC** (Eurasian Economic Standards Council; the
+Cyrillic МГС council) publications using the Relaton model. It
+is **index-backed** (no scraping): it searches a pre-built index via
+`Relaton::Index` and fetches per-document YAML from the
+`relaton/relaton-data-easc` GitHub repo. Reference parsing uses
+`Pubid::Easc::Identifier`.
+
+Two document series, both issued by EASC and catalogued on **mgscatalog.by**:
+
+- **ПМГ** (`pmg`) — Правила по межгосударственной стандартизации (interstate
+  standardization *rules*), e.g. `ПМГ 03-2025`, plus the defense variant
+  `ПМГ В 31-2001`.
+- **РМГ** (`rmg`) — Рекомендации по межгосударственной стандартизации
+  (interstate standardization *recommendations*), e.g. `РМГ 151-2025`.
+
+## Architecture
+
+Namespace: `Relaton::Easc`. Retrieval flow:
+
+1. **Bibliography** (`lib/relaton/easc/bibliography.rb`) — `get(code, year)` /
+   `search`; parses the reference with `Pubid::Easc.parse`, narrows the index by
+   number, fetches the matching YAML over `Net::HTTP`, and returns
+   `Item.from_yaml` (an `ItemData`), stamping `fetched`. EASC citations are
+   always dated (`ПМГ 03-2025`), so — unlike ISO/OIML — there is no
+   undated/most-recent handling; `get` just returns what `search` resolves.
+   `ENDPOINT` is the `relaton-data-easc/main` raw base; `INDEXFILE` (`index-v2`)
+   is defined in `lib/relaton/easc.rb`.
+2. **Index keying** — `Relaton::Index.find_or_create(:easc, url: ...,
+   pubid_class: ::Pubid::Easc::Identifier)`. `Pubid::Easc` (from
+   `metanorma/pubid`) parses both the Cyrillic surface forms and the Latin
+   transliterations (`PMG`/`RMG`/`V`) and renders canonical Cyrillic; its
+   attributes are `series` (`"PMG"|"RMG"`, Latin-canonical), `variant`
+   (`"V"|nil` — the «В» defense marker), `number`, `year`, and it serializes to
+   `_type: pubid:easc:{pmg,rmg}`. `Bibliography#pubid_match?` matches on
+   series + variant + number (nil-tolerant year), so ПМГ never matches РМГ and
+   the «В» variant never matches the plain series.
+3. **Item / ItemData / Ext** (`item.rb`, `item_data.rb`, `ext.rb`,
+   `item_base.rb`, `bibitem.rb`, `bibdata.rb`) — `Item` extends `Bib::Item`
+   with the typed `Ext` subclass; `Bibitem`/`Bibdata` alias it. `Ext` carries
+   the EASC-specific fields so they round-trip natively through both XML and
+   YAML (no per-repo merge hacks): `urn` (`urn:easc:<series>:...`), `webpage`
+   (mgscatalog.by detail URL), `session` (adopting МГС council session, e.g.
+   `67МГС`), `developer` (Разработчик), `joining_states` (collection of country
+   codes, e.g. `%w[АРМ БЕИ КАЗ]`), and `assigned_to` (Закреплен за).
+4. **Docidentifier** (`docidentifier.rb`) — a plain `Bib::Docidentifier`
+   subclass; the `content` is the canonical Cyrillic citation (`ПМГ 03-2025`).
+   Subclassed so future `#pubid` integration can hook in without changing the
+   public interface.
+5. **Doctype** (`doctype.rb`) — `TYPES = %w[pmg rmg]`.
+6. **Processor** (`lib/relaton/easc/processor.rb`) — registry integration;
+   `@prefix = "EASC"`, `@idtype = "EASC"`, and `@defaultprefix =
+   %r{^(?:ПМГ|РМГ|PMG|RMG)\b}` routes **both** Cyrillic and Latin series
+   prefixes here. `get` delegates to `Bibliography.get`. Per the lazy-registry
+   invariant, each method `require_relative "../easc"` before touching a flavor
+   constant, including `remove_index_file`.
+
+There are no scrapers — everything comes from the curated index + GitHub YAML.
+
+## Grammar (upstream, not yet present)
+
+The RelaxNG schemas in the repo-root `grammar/` are **copies of the upstream
+source of truth** `metanorma/metanorma-model-iso/grammars/` (authored as `.rnc`,
+compiled to `.rng`). There is **no EASC grammar upstream yet**, so this flavor
+intentionally ships **no** `grammar/relaton-easc*.rng` and **no** Jing/XML-schema
+validation spec. Adding the upstream `relaton-easc.rnc` (extending
+`BibDataExtensionType` with the `Ext` elements above, à la the plateau pattern)
+is tracked as a cross-project hand-off to metanorma-model-iso; once it lands,
+copy the compiled pair into `grammar/` and add the round-trip Jing spec.
+
+## Testing
+
+RSpec + WebMock. `spec/easc/support/webmock.rb` builds an offline `index-v2`
+in-memory from `Pubid::Easc` identifiers (so each row round-trips through
+`from_hash`/`to_hash` like a published index), preloads it into the
+`Relaton::Index` pool in `before(:suite)`, and stubs per-document requests from
+`spec/easc/fixtures/data/*.yaml`. No test hits the network. Run with
+`bundle exec rake spec:easc`.

data/lib/relaton/ecma/CLAUDE.md

@@ -0,0 +1,217 @@
+# CLAUDE.md
+
+## Development
+
+- `bundle install` — install dependencies
+- `bundle exec rake spec:ecma` — run this flavor's suite (from the repo root)
+- The ECMA flavor needs pubid support that is not in the released
+  `2.0.0.pre.alpha.8`, so the root `Gemfile` git-pins pubid. Pick it up with
+  **`bundle update pubid`**, never `bundle install` — see the
+  stale-pubid-lock trap in the root `CLAUDE.md`.
+
+## Pubid-backed docidentifier
+
+`Relaton::Ecma::Docidentifier` parses its `content` into a
+`Pubid::Ecma::Identifier` kept in `@pubid`, while the lutaml `content` attribute
+stays a plain **string** for serialization. Parsing is **soft**: `content=`
+lazily requires pubid and rescues `LoadError`/`StandardError`, so a missing gem
+or non-ECMA content leaves `@pubid` nil rather than raising. All three mutators
+therefore no-op safely, and `Bib::ItemData`'s `#to_all_parts` /
+`#to_most_recent_reference` never raise on ECMA items.
+
+**The one ECMA-specific rule — `refresh_content!` renders**
+**`to_s(with_edition: false, with_volume: false)`.**
+
+`Pubid::Ecma::Identifier#to_s` renders the edition and the volume **by default**
+(`"ECMA-269 ed3 vol2"`). That default is deliberate on the pubid side, because
+the index keys on a bare `to_s` — see below. A **document's own** docidentifier
+is the opposite: every `ECMA-269` volume file in `relaton-data-ecma` carries
+`docidentifier: ECMA-269` and the same title, so the edition and the volume are
+index metadata, not part of the printed id. Without the opt-out, any mutation
+would silently promote the stored content to the index form.
+
+This is the mirror image of `Relaton::ThreeGpp::Docidentifier`, whose
+`refresh_content!` must pass `with_publisher: true` because *its* pubid defaults
+to the index rendering and *its* stored content is the fuller one. The two look
+contradictory only until you notice each re-renders what its own `content`
+already holds.
+
+Component mapping:
+
+- **`remove_date!` → clears `edition`.** ECMA has no date component; `edition`
+  is its version discriminator. It is invisible in the rendered bare form, but
+  the identifier really does change and a consumer reading `#pubid` sees it.
+- **`remove_part!` → clears `part`/`subpart`.** Real here: `ECMA-418-1` →
+  `ECMA-418`.
+- **`to_all_parts!` → both, then wraps `@pubid` in pubid's `AllParts`.**
+  `content` stays the plain stripped id — the ECMA renderer has no
+  "(all parts)" marker, and `content` is cached from the pre-wrap pubid on
+  purpose. `#pubid` itself, read directly, now answers `all_parts? == true`
+  and renders WITH pubid's generic marker (`#to_s`), since it's the wrapper.
+
+## Index
+
+### The gem builds and reads `index-v2`; the data repo derives `index-v1`
+
+`INDEXFILE` is the pubid-backed `index-v2`: rows are `Pubid::Ecma::Identifier`
+hashes (`_type: pubid:ecma:{standard,technical-report,memento}` with
+`number`/`part`/`edition`/`volume`). The consumer (`Bibliography#index`) and
+the producer (`DataFetcher#index`) pass
+`pubid_class: ::Pubid::Ecma::Identifier`. Omitting it on the **producer** writes
+v1-shaped rows under a v2 name, silently (`FileIO#save` calls `to_hash` only for
+instances of `pubid_class`); omitting it on the **consumer** leaves the rows raw
+hashes with `FileIO#sorted` false, so every lookup scans all 804.
+`Processor#remove_index_file` passes `url: true` and `file:` only: the delete
+never reads the index (see `lib/relaton/index/CLAUDE.md`).
+
+This gem no longer produces the legacy `index-v1`. `relaton-data-ecma`'s
+`crawler.rb` derives it from the v2 rows, the IANA/BIPM/W3C shape.
+
+**Why the edition must be in the key.** `Index::Type#add_or_update` keys on a
+**bare** `id.to_s`, and 740 of the 804 published rows carry an edition. Before
+pubid rendered it, those 804 rows collapsed onto 421 keys — `ECMA-74` 22 rows to
+1, `ECMA-262` 18 to 1 — so a crawl would drop **383 of 804 rows and report
+success**. Four rows also need `volume`: `ECMA-269` edition 3, volumes 1-4 share
+one docidentifier *and* one title, so the volume is the only thing that tells
+them apart.
+
+**`#index_id` builds the identifier from the MODEL, not from a rendered string.**
+It takes the docidentifier's own pubid, **duplicates** it, then sets `edition`
+from `bib.edition.content` and `volume` from the extent locality — the same
+three fields `#filename_id` reads. The `dup` is load-bearing: those two are
+index metadata, so setting them on the shared object would promote the
+document's own printed id to the index form. Filenames are unaffected either
+way; `output_file` is fed by `#filename_id`, giving `ecma-269-3-1.yaml`.
+
+**An unparseable docid is recorded, not just warned.** `#add_to_index` writes
+`@errors[docid] = "Unparseable primary id … was not indexed (…)"`, which the
+inherited `report_errors` logs and `Logger::Channels::GhIssue` turns into a
+GitHub issue at the end of the crawl. (`Core::DataFetcher#report_errors` treats
+a **String** value as the message; the `@errors[:key] &&= …` boolean form the
+parsers use means "this field failed for every record" and is the wrong shape
+here.) The row is skipped rather than indexed unparsed, because
+`Relaton::Index` rejects the **whole** index if one row fails to deserialize and
+its sort calls `.root.number` on every id. The data file is still written, so
+the document is unindexed, never lost. (The 3GPP/W3C precedent.)
+
+Verified against the live published corpus: all 804 rows build an identifier,
+they render **804 distinct keys** (not 421), `root.number` is empty for none,
+`from_hash(to_hash)` round-trips all 804, and the four `ECMA-269` volumes stay
+distinct.
+
+### Lookup: `best_match`
+
+`Bibliography#search` follows the ETSI/W3C/OGC idiom:
+
+- **Pass the pubid, not the string.** `Type#search_candidates` narrows only when
+  the argument is not a `String`, and a block alone never narrows — so the plain
+  string this flavor used to pass disabled the binary search however the index
+  was built. `pubid_class:` alone fixes nothing; both had to change together.
+  Measured: `ECMA-269` now narrows to 12 of 804 rows.
+- **Select with the subset match.** `search` calls `index.search(pubid)` with
+  no block, so `Index::Type#search` selects with pubid's `pubid === row`. An
+  `edition` or `volume` that the reference omits matches any value; they are
+  index metadata that a document's own docidentifier never carries. pubid
+  declares `part` strict for ECMA (pubid#408), so a bare `ECMA-418` does not
+  match `ECMA-418-1`. `===` requires the same class, which keeps `ECMA-100`
+  and `ECMA TR/100` apart. Measured over the 804-row fixture: `===` and the
+  old `matches?(…, ignore: %i[edition volume])` agree on all 6,492 pairs.
+- **An unparseable reference finds nothing**, with a warning. There is
+  deliberately no substring-scan fallback (OGC has one): an ECMA row renders as
+  `ECMA-262 ed17`, so a scan would answer a truncated `ECMA-26` with every
+  ECMA-26x document, and an ambiguous answer is worse than none.
+
+**A reference must now parse WHOLE.** The old `parse_ref` regex was unanchored
+at the end, so trailing text after a valid prefix was ignored and still
+resolved; pubid rejects it. Measured:
+
+| reference | old | new |
+|---|---|---|
+| `ECMA-6 (draft)` | `ECMA-6` | none |
+| `ECMA-6:1991` | `ECMA-6` | none |
+| `ECMA-6 2nd edition` | `ECMA-6` | none |
+| `ECMA-6 ` (trailing space) | `ECMA-6` | `ECMA-6` |
+| ` ECMA-6` (leading space) | none | `ECMA-6` — `parse_ref` strips |
+
+That is the same trade-off as the missing fallback — a strict parse beats an
+ambiguous match — and it is the first thing to check against a report that a
+reference "used to resolve and now does not". `ecma-6` (lowercase) parsed under
+neither.
+
+#### Ordering: latest edition, then lowest volume
+
+That is the order the bespoke `compare_edition_volume` + `min` implemented, kept
+deliberately — but the edition is compared **segment-wise as integers**
+(`edition_key`), and `r[:file]` breaks the tie because the index sort is not
+stable. Comparing the rendered strings made `"9"` beat `"17"`, so 5 of the 421
+document families returned an older document than the reference asked for.
+Scored against each document's own published date:
+
+| family | string compare | integer compare | dates |
+|---|---|---|---|
+| ECMA-262 | ed9 | **ed17** | 2018-06 → 2026-06 |
+| ECMA-74 | ed9 | **ed22** | 2005-12 → 2025-12 |
+| ECMA-402 | ed9 | **ed13** | → 2026-06 |
+| ECMA-328 | ed7 | **ed10** | same direction |
+| ECMA-109 | ed9 | **ed11** | same direction |
+
+The integer key picks the newer document in all 5. An absent edition sorts below
+every present one — right for the 64 edition-less rows (mementos, a few
+reports), none of which shares a document with an edition-bearing row.
+
+**`ECMA-262 ed5.1` is the only dotted edition in the whole published corpus.**
+It is what forces the segment-wise compare (`5.1` must beat `5`), but since 262's
+latest is ed17 the dotted ordering never decides a bare lookup — so it is pinned
+by a unit assertion on `edition_key` rather than by an end-to-end example. Do not
+"simplify" the key to `to_i`.
+
+The old `match_ref` also matched on a **prefix** (`/^ECMA[-\s]#{id}/`), so
+`ECMA-43` matched `ECMA-430…434`. Four families collided this way (418, 43, 35,
+13); none of the four changed its answer, so exact matching removed a latent
+risk rather than moving results.
+
+#### Verified against the published index
+
+`relaton-data-ecma` publishes `index-v2.zip`. Loaded through
+`Bibliography#index`: **804 rows**, all deserialized to identifiers, sorted,
+**0** keying on `""`, 804 distinct keys, and `from_hash(to_hash)` round-trips
+every row. Live lookups resolve every shape the flavor handles, each to a file
+that returns HTTP 200 — a bare `ECMA-269` → ed9, the space form `ECMA 269` →
+the same, `ECMA-269 ed3` → vol1, all four `ed3 vol<N>`, `ECMA-262` → ed17
+(2026-06), `ECMA-262 ed5.1`, `ECMA-418` vs `ECMA-418-1`, `ECMA-100` vs
+`ECMA TR/100`, `ECMA MEM/2021`, and `ECMA-43` narrowed to number `43` alone.
+
+## Testing
+
+- **Framework:** RSpec with VCR cassettes and WebMock.
+- **Index fixture:** `spec/ecma/fixtures/index-v2.zip` — the whole published
+  index (804 rows), copied verbatim, so the stored shapes are exactly what the
+  runtime deserializes. Refresh it with `bundle exec rake spec:update_index_ecma`
+  (`tasks/index_fixture_ecma.rb`); `#build` refuses a source that is not a pubid
+  index-v2 rather than writing a fixture `Relaton::Index` would reject wholesale.
+- It is seeded into the `Relaton::Index` pool by `spec/ecma/support/webmock.rb`,
+  built **with `pubid_class:`** — without it the rows stay raw hashes,
+  `FileIO#sorted` stays false, and `Type#search` silently stops narrowing, so the
+  suite would pass while exercising something the runtime never does. Seeded in
+  `before(:each)`, not only `before(:suite)`, because `Index::Pool#type` replaces
+  the pooled entry whenever `actual?` says no and `DataFetcher#index` asks for
+  the same type with `file:` but no `url:`. With `before(:suite)` alone every
+  example after the first data-fetcher one searched a producer index, and the
+  consumer then built a third type and went to the network for real. The pool key
+  is `type.upcase.to_sym`, so the fetcher's `:ecma` and the consumer's `:ECMA`
+  share one slot. (The OGC pattern.)
+- **VCR cassettes:** `spec/ecma/vcr_cassettes/` — index downloads are ignored by
+  VCR, matched on `INDEXFILE` so a version bump cannot let a real download
+  through.
+- `spec/ecma/relaton/ecma/index_key_spec.rb` checks the whole fixture corpus for
+  the properties the index depends on: every row deserializes, one distinct
+  rendered key per row, no empty bsearch key, sorted, and a `to_hash` round-trip.
+- A live check of the flavor cannot use `Bibliography.get` behind an HTTP proxy:
+  the document fetch goes through **Mechanize**, which does not read
+  `http_proxy`/`https_proxy` the way `Net::HTTP` does, so it dies with a
+  connection error on a host `curl` reaches. The index download (`Net::HTTP`)
+  works, so drive `best_match` and fetch the resolved file with `Net::HTTP`
+  instead.
+- The `bibdata`/`bibitem` round-trip examples validate XML with Jing, which
+  needs a **JVM on PATH**. Without one they fail with `Jing::ExecutionError`;
+  that is environmental, not a code defect.

data/lib/relaton/ecma/README.adoc

@@ -0,0 +1,178 @@
+= Relaton::Ecma
+
+Relaton::Ecma is a Ruby gem that searches and fetches standards from the https://www.ecma-international.org[European Computer Manufacturers Association].
+
+== Usage
+
+=== Fetch documents
+
+Documents can be fetched by reference. The structure of the reference depends on the type of the document. There are three types of documents:
+
+- ECMA standards
+- ECMA technical reports
+- ECMA mementos
+
+ECMA standards have the following reference structure: `ECMA-{NUMBER}[ ed{EDITION}][ vol{VOLUME}]`. Where: `NUMBER` is a number of the standard, `EDITION` is an edition of the standard, and `VOLUME` is a volume of the standard. The `EDITION` and `VOLUME` are optional. If `EDITION` is not specified, the latest edition of the standard will be fetched. If `VOLUME` is not specified, the first volume of the standard will be fetched. +
+
+ECMA technical reports have the following reference structure: `ECMA TR/{NUMBER}[ ed{EDITION}]`. Where: `NUMBER` is a number of the technical report, and `EDITION` is an edition of the technical report. The `EDITION` is optional. If `EDITION` is not specified, the latest edition of the technical report will be fetched. +
+
+ECMA mementos have the following reference structure: `ECMA MEM/{YEAR}`. Where: `YEAR` is an year of the memento.
+
+[source,ruby]
+----
+require 'relaton/ecma'
+=> true
+
+# fetch ECMA standard
+item = Relaton::Ecma::Bibliography.get 'ECMA-6'
+[relaton-ecma] INFO: (ECMA-6) Fetching from Relaton repository ...
+[relaton-ecma] INFO: (ECMA-6) Found: `ECMA-6`
+=> #<Relaton::Ecma::ItemData:0x000000012791d7a0
+...
+
+# fetch ECMA standard with edition and volume
+Relaton::Ecma::Bibliography.get "ECMA-269 ed3 vol2"
+[relaton-ecma] INFO: (ECMA-269 ed3 vol2) Fetching from Relaton repository ...
+[relaton-ecma] INFO: (ECMA-269 ed3 vol2) Found: `ECMA-269`
+=> #<Relaton::Ecma::ItemData:0x0000000127b81410
+...
+
+# fetch the last edition of ECMA standard
+bib = Relaton::Ecma::Bibliography.get "ECMA-269"
+[relaton-ecma] INFO: (ECMA-269) Fetching from Relaton repository ...
+[relaton-ecma] INFO: (ECMA-269) Found: `ECMA-269`
+=> #<Relaton::Ecma::ItemData:0x0000000127cd0a00
+...
+
+bib.edition.content
+=> "9"
+
+# fetch the first volume of ECMA standard
+bib = Relaton::Ecma::Bibliography.get "ECMA-269 ed3"
+[relaton-ecma] INFO: (ECMA-269 ed3) Fetching from Relaton repository ...
+[relaton-ecma] INFO: (ECMA-269 ed3) Found: `ECMA-269`
+=> #<Relaton::Ecma::ItemData:0x0000000127cf7808
+...
+
+bib.extent.first.locality.first.reference_from
+=> "1"
+
+# fetch ECMA technical report
+Relaton::Ecma::Bibliography.get 'ECMA TR/18'
+[relaton-ecma] INFO: (ECMA TR/18) Fetching from Relaton repository ...
+[relaton-ecma] INFO: (ECMA TR/18) Found: `ECMA TR/18`
+=> #<Relaton::Ecma::ItemData:0x0000000127cdc940
+...
+
+# fetch ECMA memento
+Relaton::Ecma::Bibliography.get "ECMA MEM/2021"
+[relaton-ecma] INFO: (ECMA MEM/2021) Fetching from Relaton repository ...
+[relaton-ecma] INFO: (ECMA MEM/2021) Found: `ECMA MEM/2021`
+=> #<Relaton::Ecma::ItemData:0x0000000127cf71c8
+...
+
+# Return nil if a document doesn't exist.
+Relaton::Ecma::Bibliography.get '1111'
+[relaton-ecma] INFO: (1111) Fetching from Relaton repository ...
+[relaton-ecma] WARN: Failed to parse pubid `1111`: Failed to parse ECMA identifier '1111': ...
+[relaton-ecma] INFO: (1111) Not found.
+=> nil
+----
+
+=== Serialization
+
+[source,ruby]
+----
+item.to_xml
+=> "<bibitem id="ECMA6" type="standard" schema-version="v1.5.6">
+      <fetched>2025-12-29</fetched>
+      <title language="en" script="Latn">7-bit coded character set</title>
+      <uri type="src">https://ecma-international.org/publications-and-standards/standards/ecma-6/</uri>
+      <uri type="pdf">https://ecma-international.org/wp-content/uploads/ECMA-6_6th_edition_december_1991.pdf</uri>
+      <docidentifier type="ECMA" primary="true">ECMA-6</docidentifier>
+      ...
+    </bibitem>"
+----
+
+With `bibdata: true` option XML output wrapped with `bibdata` element and `ext` element added.
+[source,ruby]
+----
+item.to_xml bibdata: true
+=> "<bibdata type="standard" schema-version="v1.5.6">
+      <fetched>2025-12-29</fetched>
+      <title language="en" script="Latn">7-bit coded character set</title>
+      <uri type="src">https://ecma-international.org/publications-and-standards/standards/ecma-6/</uri>
+      <uri type="pdf">https://ecma-international.org/wp-content/uploads/ECMA-6_6th_edition_december_1991.pdf</uri>
+      <docidentifier type="ECMA" primary="true">ECMA-6</docidentifier>
+      ...
+      <ext schema-version="v1.0.0">
+        <doctype>document</doctype>
+        <flavor>ecma</flavor>
+      </ext>
+    </bibdata>"
+----
+
+=== Typed links
+
+Each ECMA document has `src` and `doi` link types.
+
+[source,ruby]
+----
+item.source
+=>
+[#<Relaton::Bib::Uri:0x00000001278dc5e8 @content="https://ecma-international.org/publications-and-standards/standards/ecma-6/", @language=nil, @locale=nil, @script=nil, @type="src">,
+ #<Relaton::Bib::Uri:0x00000001278dc188
+  @content="https://ecma-international.org/wp-content/uploads/ECMA-6_6th_edition_december_1991.pdf",
+  @language=nil,
+  @locale=nil,
+  @script=nil,
+  @type="pdf">]
+----
+
+=== Parse a file locally
+
+[source,ruby]
+----
+item = Relaton::Ecma::Item.from_xml File.read("spec/fixtures/bibdata.xml")
+=> #<Relaton::Ecma::ItemData:0x0000000127cbb1a0
+...
+----
+
+=== Fetch data
+
+This gem uses a https://github.com/relaton/relaton-data-ecma[ecma-standards] prefetched dataset as a data source. The dataset contains documents from ECMA https://www.ecma-international.org/publications-and-standards/standards/[Standards], https://www.ecma-international.org/publications-and-standards/technical-reports/[Technical Reports], and https://www.ecma-international.org/publications-and-standards/mementos/[Mementos] pages.
+
+The method `Relaton::Ecma::DataFetcher.new(output, format).fetch` fetches all the documents from the pages and saves them to the `./data` folder in YAML format.
+Arguments:
+
+- `output` - folder to save documents (default './data').
+- `format` - the format in which the documents are saved. Possible formats are: `yaml`, `xml`, `bibxxml` (default `yaml`).
+
+[source,ruby]
+----
+Relaton::Ecma::DataFetcher.new.fetch
+Started at: 2022-06-23 09:36:55 +0200
+Stopped at: 2022-06-23 09:36:58 +0200
+Done in: 752 sec.
+=> nil
+----
+
+=== Logging
+
+Relaton::Ecma uses the relaton-logger gem for logging. By default, it logs to STDOUT. To change the log levels and add other loggers, read the https://github.com/relaton/relaton-logger#usage[relaton-logger] documentation.
+
+== Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To update the index test fixture (used by tests), run `rake spec:update_index`. This downloads the latest `index-v1.zip` from the https://github.com/relaton/relaton-data-ecma[relaton-data-ecma] repository.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/relaton/relaton-ecma.
+
+== License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/relaton/equivalence.rb

@@ -0,0 +1,89 @@
+require "yaml"
+
+module Relaton
+  # Cross-SDO equivalence as data: chain patterns and explicit equivalences
+  # the resolver consults when a reference misses. Tables are YAML files
+  # (schema: data/equivalence/adoption-chains.yaml); the gem ships the seed
+  # table and callers register more with {.register}.
+  module Equivalence
+    class << self
+      # @return [Array<Hash>] loaded tables, innermost last
+      def tables
+        @tables ||= []
+      end
+
+      # Register a table file or every *.yaml under a directory. Later
+      # registrations take precedence (checked first).
+      #
+      # @param [String] path file or directory
+      # @return [Array<Hash>] the tables now loaded
+      def register(path)
+        files = if File.directory?(path)
+                  Dir.glob(File.join(path, "*.yaml")).sort.reverse
+                else
+                  [path]
+                end
+        files.each { |f| tables << YAML.safe_load_file(f, aliases: true) }
+        tables
+      end
+
+      # Load the gem's seed table (idempotent). {Db} calls this on first use.
+      def load_seed
+        register(seed_path) unless tables.any?
+        tables
+      end
+
+      def seed_path
+        File.join(__dir__, "..", "..", "data", "equivalence", "adoption-chains.yaml")
+      end
+
+      # Reset (spec seam).
+      def reset!
+        @tables = nil
+      end
+
+      # The canonical reference for `code`, or nil when no table maps it.
+      # The code itself is not returned: a miss on a canonical form stays a
+      # miss.
+      #
+      # @param [String] code
+      # @return [String, nil]
+      def canonical_for(code)
+        load_seed
+        tables.each do |table|
+          (table["equivalences"] || []).each do |eq|
+            next if eq["canonical"] == code
+            next unless Array(eq["equivalents"]).include?(code)
+
+            return eq["canonical"]
+          end
+          (table["chains"] || []).each do |chain|
+            m = Regexp.new(chain["match"]).match(code)
+            next unless m
+
+            chain["resolve"].each do |template|
+              candidate = template.gsub(/\\(\d+)/) { m[Regexp.last_match(1).to_i] }
+              return candidate unless candidate == code
+            end
+          end
+        end
+        nil
+      end
+
+      # Every equivalent of `code`, canonical form first, the code itself
+      # excluded.
+      #
+      # @param [String] code
+      # @return [Array<String>]
+      def equivalents_for(code)
+        out = []
+        cursor = code
+        while (next_code = canonical_for(cursor)) && !out.include?(next_code)
+          out << next_code
+          cursor = next_code
+        end
+        out
+      end
+    end
+  end
+end