relaton 1.20.1 → 1.20.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13dbf084ccd28b8edc98d3e9b8774eb6eef7998f73627332fb7f92809cf635fd
-  data.tar.gz: d81e1084ff58259e9d2f91d1cbbb1b6590ab6531a15f643209091fcdba1ea978
+  metadata.gz: 94c3b2f7f4a364ddd5771661f9bb0c2d6e4d393fe9608a53ee4e1270e3431092
+  data.tar.gz: de220c6644cc24fdc75f1be9b7ceff7a8631e26c76a62c8ced7d514d58a50621
 SHA512:
-  metadata.gz: b6191397dde96436e07a88c62b4995991f50b1aae1d347a52b5ee5262e494498a4c7991ff62e9924086e39023956342900a914d527b77bfa8299b2b97c13b89d
-  data.tar.gz: 817aca4c0d54b585cffa7d14c1645fa9bcd078aa281ab33aaa51e8c2cc125a07d4ea6a268b62b507baa06dce66410c2d2cd46a9fb7fd0ad019636e6470ce9d6b
+  metadata.gz: 621a9fa3ed13274e4f031eec041c26436824ce1fe5020ad7deffbec4d3c218f71a467104af276568ccec4fcc9b93a79362d7eb5d61b59d0308bede27e9df7d33
+  data.tar.gz: a8e60d3d61262b91617a9c0090a1220b8ac36b0cffcfabd683519b6da43713157235d74f0d72d09def1e7d78dff966133629a57ab4d2cd17441313e760d3fbb9

data/.github/workflows/rubocop.yml

@@ -0,0 +1,48 @@
+name: Rubocop
+
+on: pull_request
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  rubocop:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+      - name: Determine Ruby version for ruby/setup-ruby
+        shell: bash
+        run: |
+          RUBY_VERSION=${{ vars.RUBY_VERSION }}
+
+          if [[ -r .rubocop.yml ]]
+          then
+            RUBY_VERSION=$( \
+              command grep \
+              -E '^\s*TargetRubyVersion:\s*[0-9]+(\.[0-9]+)*' \
+              .rubocop.yml \
+              | command awk '{print $2}' \
+            )
+          fi
+
+          if [[ -z $RUBY_VERSION ]]
+          then
+            # Let setup-ruby determine the Ruby version if no .ruby-version,
+            # .tool-versions or mise.toml file exists
+            RUBY_VERSION=default
+          fi
+
+          echo "RUBY_VERSION=$RUBY_VERSION" >> $GITHUB_ENV
+      - uses: ruby/setup-ruby@v1
+        with:
+          # input ruby-version needs to be specified if no .ruby-version,
+          # .tool-versions or mise.toml file exists
+          #
+          # Use the version that matches the one in gemspec & .rubocop.yml
+          ruby-version: ${{ env.RUBY_VERSION }}
+      - uses: reclaim-the-stack/rubocop-action@v1.1.0
+        with:
+          gem_versions: rubocop:1.84.2 rubocop-performance:1.26.1 rubocop-rails:2.34.3

data/.gitignore

@@ -8,3 +8,5 @@ testcache2
 .vscode/
 pkg/
 Gemfile.lock
+.rubocop-remote-87c7cdd254a8d09d005ee06efac7acc0.yml
+.claude/

data/.rubocop.yml

@@ -2,11 +2,11 @@
 # https://github.com/riboseinc/oss-guides
 # All project-specific additions and overrides should be specified in this file.
 
-require: rubocop-rails
+plugins: rubocop-rails
 
 inherit_from:
   - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
 AllCops:
-  TargetRubyVersion: 3.0
+  TargetRubyVersion: 3.1
 Rails:
   Enabled: false

data/CLAUDE.md

@@ -0,0 +1,68 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Run full test suite
+bundle exec rake        # or: bundle exec rspec
+
+# Run a single spec file
+bundle exec rspec spec/relaton/db_spec.rb
+
+# Run a specific test by line number
+bundle exec rspec spec/relaton/db_spec.rb:234
+
+# Lint
+bundle exec rubocop
+
+# Lint with auto-fix
+bundle exec rubocop -a
+```
+
+## Architecture
+
+Relaton is a Ruby gem that fetches, caches, and manages bibliographic references to technical standards from 25+ organizations (ISO, IEC, IETF, NIST, IEEE, etc.).
+
+### Plugin Registry Pattern
+
+**Relaton::Registry** (singleton) auto-discovers and manages backend processor gems (relaton-iso, relaton-iec, relaton-ietf, etc.). Each processor implements the **Relaton::Processor** interface (`get`, `from_xml`, `hash_to_bib`, `prefix`, `defaultprefix`). The registry routes reference codes to the correct processor by matching prefixes (e.g., "ISO 19115" → `:relaton_iso`).
+
+### Db (lib/relaton/db.rb) — Main Public API
+
+`Relaton::Db#fetch(ref, year, opts)` is the primary entry point. It:
+1. Identifies the processor via Registry prefix matching
+2. Handles combined references (`+` for derivedFrom, `,` for amendments) in `combine_doc`
+3. Delegates to `check_bibliocache` which manages the dual-cache lookup and network fetch flow
+
+The dual-cache strategy uses a **global cache** (`~/.relaton/cache`) and an optional **local cache** (project-level). `check_bibliocache` checks local first, falls back to global, and syncs between them.
+
+### DbCache (lib/relaton/db_cache.rb) — File-based Storage
+
+Stores entries as files under `{dir}/{prefix}/{filename}.{ext}` (e.g., `testcache/iso/iso_19115-1.xml`). Key behaviors:
+- Cache keys are wrapped like `ISO(ISO 19115-1:2014)` and converted to filenames via regex
+- Entries can be XML, "not_found {date}", or "redirection {target_key}"
+- Undated references expire after 60 days; dated ones persist indefinitely
+- Version tracking per prefix directory invalidates cache when processor grammar changes
+- File locking (`LOCK_EX`) for thread-safe concurrent writes
+
+### WorkersPool (lib/relaton/workers_pool.rb)
+
+Thread pool for `fetch_async`. Default 10 threads per processor, overridable via `RELATON_FETCH_PARALLEL` env var.
+
+### Cache Key Format
+
+`std_id` builds keys like `ISO(ISO 19115-1:2014 (all parts) after-2020-01-01)`. The filename regex in `db_cache.rb` uses `[^)]+` — suffixes use `-` not parentheses to avoid breaking it.
+
+## Testing
+
+- RSpec with VCR cassettes in `spec/vcr_cassetes/` for recorded HTTP interactions
+- Tests create `testcache`/`testcache2` directories and clean them in `before(:each)`
+- Cache-related tests need `<fetched>` elements in XML for `valid_entry?` to return true
+- Integration tests in `spec/relaton_spec.rb`; unit tests mirror `lib/` structure under `spec/relaton/`
+
+## Style
+
+- RuboCop config inherits from [Ribose OSS guides](https://github.com/riboseinc/oss-guides), target Ruby 3.1
+- Thread safety via `@semaphore` (Mutex) around cache reads/writes in Db

data/Gemfile

@@ -3,16 +3,16 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in gemspec
 gemspec
 
-gem "byebug", "~> 11.0"
+gem "byebug"
 gem "equivalent-xml", "~> 0.6"
 gem "guard", "~> 2.14"
 gem "guard-rspec", "~> 4.7"
-gem "pry-byebug", "~> 3.9.0"
+gem "pry-byebug"
 gem "rake", "~> 13.0"
 gem "rspec", "~> 3.6"
-gem "rubocop", "~> 1.17.0"
-gem "rubocop-performance", "~> 1.11.0"
-gem "rubocop-rails", "~> 2.10.0"
+gem "rubocop"
+gem "rubocop-performance"
+gem "rubocop-rails"
 gem "simplecov", "~> 0.15"
 gem "timecop", "~> 0.9"
 gem "vcr", "~> 6"

data/docs/README.adoc

@@ -176,6 +176,8 @@ Arguments:
 - `:keep_yer` - (Boolean) should be `true` if undated reference should return an actual reference with the year
 - `:retries` - (Number) number of network retries. Default 1
 - `:no_cache` - (Boolean) should be `true` if cache should be ignored
+- `:publication_date_after` - (String) filter for documents published on or after this date (inclusive, `"YYYY-MM-DD"`)
+- `:publication_date_before` - (String) filter for documents published before this date (exclusive, `"YYYY-MM-DD"`)
 
 [source,ruby]
 ----
@@ -235,6 +237,24 @@ refs.size.times do
 end
 ----
 
+==== Fetch with publication date filter
+
+The `:publication_date_after` and `:publication_date_before` options restrict results to documents published within a date range. The range is inclusive of `:publication_date_after` and exclusive of `:publication_date_before`.
+
+When a date filter is used, the cache is checked first for an existing entry whose publication date satisfies the range. If no match is found, a date-specific cache entry is created.
+
+[source,ruby]
+----
+# Fetch documents published on or after 2018-01-01
+x = db.fetch("ISO 19115-1", nil, publication_date_after: "2018-01-01")
+
+# Fetch documents published before 2020-01-01
+x = db.fetch("ISO 19115-1", nil, publication_date_before: "2020-01-01")
+
+# Fetch documents published within a range
+x = db.fetch("ISO 19115-1", nil, publication_date_after: "2018-01-01", publication_date_before: "2020-01-01")
+----
+
 ==== Fetch by URN
 
 This functionality works only for IEC documents.

data/lib/relaton/db.rb

@@ -47,6 +47,11 @@ module Relaton
     #   actual reference with year
     # @option opts [Integer] :retries (1) Number of network retries
     # @option opts [Boolean] :no_cache If true then don't use cache
+    # @option opts [String] :publication_date_before published before this date
+    #  (exclusive, formats: "YYYY", "YYYY-MM", or "YYYY-MM-DD")
+    # @option opts [String] :publication_date_after published on or
+    #  after this date (inclusive, formats: "YYYY", "YYYY-MM",
+    #  or "YYYY-MM-DD")
     #
     # @return [nil, RelatonBib::BibliographicItem,
     #   RelatonIsoBib::IsoBibliographicItem, RelatonItu::ItuBibliographicItem,
@@ -329,6 +334,12 @@ module Relaton
       ret = code
       ret += (stdclass == :relaton_gb ? "-" : ":") + year if year
       ret += " (all parts)" if opts[:all_parts]
+      if opts[:publication_date_after]
+        ret += " after-#{opts[:publication_date_after]}"
+      end
+      if opts[:publication_date_before]
+        ret += " before-#{opts[:publication_date_before]}"
+      end
       ["#{prefix}(#{ret.strip})", code]
     end
 
@@ -379,6 +390,23 @@ module Relaton
     #   RelatonBipm::BipmBibliographicItem, RelatonIho::IhoBibliographicItem,
     #   RelatonOmg::OmgBibliographicItem, RelatonW3c::W3cBibliographicItem]
     def check_bibliocache(code, year, opts, stdclass) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+      # When date filters are present, check if the base
+      # (non-date-filtered) cache entry satisfies the range
+      if opts[:publication_date_before] || opts[:publication_date_after]
+        base_opts = opts.except(
+          :publication_date_before, :publication_date_after
+        )
+        base_id, = std_id(code, year, base_opts, stdclass)
+        db = @local_db || @db
+        if db&.valid_entry?(base_id, year)
+          entry = db[base_id]
+          if entry && !entry.match?(/^not_found/) &&
+              pub_date_in_range?(entry, opts)
+            return bib_retval(entry, stdclass)
+          end
+        end
+      end
+
       id, searchcode = std_id(code, year, opts, stdclass)
       db = @local_db || @db
       altdb = @local_db && @db ? @db : nil
@@ -512,6 +540,42 @@ module Relaton
       bib.respond_to?(:to_xml) ? bib.to_xml(bibdata: true) : "not_found #{Date.today}"
     end
 
+    # Check if an XML entry's published date falls within the requested range.
+    # Range semantics: [after, before) — inclusive start, exclusive end.
+    #
+    # @param entry [String] XML string
+    # @param opts [Hash]
+    # @return [Boolean]
+    def pub_date_in_range?(entry, opts) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+      doc = Nokogiri::XML(entry)
+      date_str = doc.at("//date[@type='published']/on")&.text
+      return false unless date_str
+
+      date = parse_pub_date(date_str)
+      return false unless date
+
+      after = opts[:publication_date_after]
+      return false if after && date < Date.parse(after.to_s)
+
+      before = opts[:publication_date_before]
+      return false if before && date >= Date.parse(before.to_s)
+
+      true
+    end
+
+    # @param str [String] date string in "YYYY", "YYYY-MM",
+    #   or "YYYY-MM-DD" format
+    # @return [Date, nil]
+    def parse_pub_date(str)
+      case str
+      when /^\d{4}-\d{1,2}-\d{1,2}/ then Date.parse(str)
+      when /^\d{4}-\d{1,2}/ then Date.strptime(str, "%Y-%m")
+      when /^\d{4}/ then Date.strptime(str, "%Y")
+      end
+    rescue ArgumentError
+      nil
+    end
+
     # @param dir [String, nil] DB directory
     # @return [Relaton::DbCache, NilClass]
     def open_cache_biblio(dir) # rubocop:disable Metrics/MethodLength

data/lib/relaton/version.rb

@@ -1,3 +1,3 @@
 module Relaton
-  VERSION = "1.20.1".freeze
+  VERSION = "1.20.2".freeze
 end

data/relaton.gemspec

@@ -27,7 +27,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
   spec.files         = `git ls-files`.split("\n")
   # spec.test_files    = `git ls-files -- {spec}/*`.split("\n")
-  spec.required_ruby_version = Gem::Requirement.new(">= 3.0.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.1.0")
 
   spec.add_dependency "relaton-3gpp", "~> 1.20.0"
   spec.add_dependency "relaton-bipm", "~> 1.20.0"
@@ -41,7 +41,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "relaton-etsi", "~> 1.20.0"
   spec.add_dependency "relaton-gb", "~> 1.20.0"
   spec.add_dependency "relaton-iana", "~> 1.20.0"
-  spec.add_dependency "relaton-iec", "~> 1.20.0"
+  spec.add_dependency "relaton-iec", "~> 1.20.3"
   spec.add_dependency "relaton-ieee", "~> 1.20.0"
   spec.add_dependency "relaton-ietf", "~> 1.20.0"
   spec.add_dependency "relaton-iho", "~> 1.20.0"
@@ -57,4 +57,5 @@ Gem::Specification.new do |spec|
   spec.add_dependency "relaton-un", "~> 1.20.0"
   spec.add_dependency "relaton-w3c", "~> 1.20.0"
   spec.add_dependency "relaton-xsf", "~> 1.20.0"
+  spec.add_development_dependency "rubocop-rails"
 end

data/spec/relaton/db_spec.rb

@@ -91,6 +91,199 @@ RSpec.describe Relaton::Db do
     end
   end
 
+  context "#pub_date_in_range?" do
+    let(:xml_with_date) do
+      <<~XML
+        <bibitem id="ISO123">
+          <title>Test</title>
+          <date type="published"><on>2019-06-15</on></date>
+        </bibitem>
+      XML
+    end
+
+    let(:xml_year_only) do
+      <<~XML
+        <bibitem id="ISO123">
+          <title>Test</title>
+          <date type="published"><on>2019</on></date>
+        </bibitem>
+      XML
+    end
+
+    let(:xml_year_month) do
+      <<~XML
+        <bibitem id="ISO123">
+          <title>Test</title>
+          <date type="published"><on>2019-06</on></date>
+        </bibitem>
+      XML
+    end
+
+    let(:xml_no_date) do
+      <<~XML
+        <bibitem id="ISO123">
+          <title>Test</title>
+        </bibitem>
+      XML
+    end
+
+    it "returns true when date is within range" do
+      result = subject.send(
+        :pub_date_in_range?, xml_with_date,
+        publication_date_after: "2019-01-01",
+        publication_date_before: "2020-01-01"
+      )
+      expect(result).to be true
+    end
+
+    it "returns false when date is before :publication_date_after" do
+      result = subject.send(
+        :pub_date_in_range?, xml_with_date,
+        publication_date_after: "2020-01-01"
+      )
+      expect(result).to be false
+    end
+
+    it "returns false when date is on or after :publication_date_before (exclusive)" do
+      result = subject.send(
+        :pub_date_in_range?, xml_with_date,
+        publication_date_before: "2019-06-15"
+      )
+      expect(result).to be false
+    end
+
+    it "returns true when date equals :publication_date_after (inclusive)" do
+      result = subject.send(
+        :pub_date_in_range?, xml_with_date,
+        publication_date_after: "2019-06-15"
+      )
+      expect(result).to be true
+    end
+
+    it "handles year-only dates" do
+      result = subject.send(
+        :pub_date_in_range?, xml_year_only,
+        publication_date_after: "2018-01-01",
+        publication_date_before: "2020-01-01"
+      )
+      expect(result).to be true
+    end
+
+    it "handles year-month dates" do
+      result = subject.send(
+        :pub_date_in_range?, xml_year_month,
+        publication_date_after: "2019-05-01",
+        publication_date_before: "2019-07-01"
+      )
+      expect(result).to be true
+    end
+
+    it "returns false when no published date exists" do
+      result = subject.send(:pub_date_in_range?, xml_no_date,
+                            publication_date_after: "2019-01-01")
+      expect(result).to be false
+    end
+
+    it "returns true with only :publication_date_after when date matches" do
+      result = subject.send(:pub_date_in_range?, xml_with_date,
+                            publication_date_after: "2019-01-01")
+      expect(result).to be true
+    end
+
+    it "returns true with only :publication_date_before when date matches" do
+      result = subject.send(:pub_date_in_range?, xml_with_date,
+                            publication_date_before: "2020-01-01")
+      expect(result).to be true
+    end
+  end
+
+  context "#std_id with date options" do
+    it "includes after suffix" do
+      id, code = subject.send(
+        :std_id, "ISO 19115-1", nil,
+        { publication_date_after: "2018-01-01" }, :relaton_iso
+      )
+      expect(id).to eq "ISO(ISO 19115-1 after-2018-01-01)"
+      expect(code).to eq "ISO 19115-1"
+    end
+
+    it "includes before suffix" do
+      id, code = subject.send(
+        :std_id, "ISO 19115-1", nil,
+        { publication_date_before: "2020-12-31" }, :relaton_iso
+      )
+      expect(id).to eq "ISO(ISO 19115-1 before-2020-12-31)"
+      expect(code).to eq "ISO 19115-1"
+    end
+
+    it "includes both after and before suffixes" do
+      id, code = subject.send(
+        :std_id, "ISO 19115-1", nil,
+        { publication_date_after: "2018-01-01",
+          publication_date_before: "2020-12-31" },
+        :relaton_iso
+      )
+      expect(id).to eq(
+        "ISO(ISO 19115-1 after-2018-01-01 before-2020-12-31)"
+      )
+      expect(code).to eq "ISO 19115-1"
+    end
+
+    it "does not change key without date options" do
+      id, code = subject.send(:std_id, "ISO 19115-1", nil, {}, :relaton_iso)
+      expect(id).to eq "ISO(ISO 19115-1)"
+      expect(code).to eq "ISO 19115-1"
+    end
+
+    it "combines with year and all_parts" do
+      id, = subject.send(
+        :std_id, "ISO 19115-1", "2014",
+        { all_parts: true,
+          publication_date_after: "2014-01-01" },
+        :relaton_iso
+      )
+      expect(id).to eq(
+        "ISO(ISO 19115-1:2014 (all parts) after-2014-01-01)"
+      )
+    end
+  end
+
+  context "#check_bibliocache with date options" do
+    let(:db) { Relaton::Db.new "testcache", nil }
+
+    before(:each) do
+      db.save_entry "ISO(ISO 123)", <<~XML
+        <bibitem id="ISO123">
+          <fetched>#{Date.today}</fetched>
+          <title>Test</title>
+          <date type="published"><on>2019-06-15</on></date>
+        </bibitem>
+      XML
+    end
+
+    after(:each) { db.clear }
+
+    it "returns base cached entry when date matches" do
+      item = db.send(
+        :check_bibliocache, "ISO 123", nil,
+        { publication_date_after: "2019-01-01",
+          fetch_db: true }, :relaton_iso
+      )
+      expect(item).to be_instance_of(
+        RelatonIsoBib::IsoBibliographicItem
+      )
+    end
+
+    it "does not return base cached entry when date does not match" do
+      item = db.send(
+        :check_bibliocache, "ISO 123", nil,
+        { publication_date_after: "2020-01-01",
+          fetch_db: true }, :relaton_iso
+      )
+      expect(item).to be_nil
+    end
+  end
+
   context "class methods" do
     it "::init_bib_caches" do
       expect(FileUtils).to receive(:rm_rf).with(/\/\.relaton\/cache$/)

data/spec/relaton_spec.rb

@@ -1,8 +1,16 @@
 RSpec.describe Relaton::Db do
-  before :each do
+  before :each do |example|
     FileUtils.rm_rf %w(testcache testcache2)
     @db = Relaton::Db.new "testcache", "testcache2"
     Relaton.instance_variable_set :@configuration, nil
+
+    if example.metadata[:vcr]
+      require "relaton/index"
+      allow_any_instance_of(Relaton::Index::Type)
+        .to receive(:actual?).and_return(false)
+      allow_any_instance_of(Relaton::Index::FileIO)
+        .to receive(:check_file).and_return(nil)
+    end
   end
 
   it "rejects an illegal reference prefix" do
@@ -255,11 +263,9 @@ RSpec.describe Relaton::Db do
     expect(bib.docidentifier.first.id).to eq "CCSDS 230.2-G-1"
   end
 
-  it "get IEEE reference" do
-    VCR.use_cassette "ieee_528_2019" do
-      bib = @db.fetch "IEEE 528-2019"
-      expect(bib).to be_instance_of RelatonIeee::IeeeBibliographicItem
-    end
+  it "get IEEE reference", vcr: "ieee_528_2019" do
+    bib = @db.fetch "IEEE Std 528-2019"
+    expect(bib).to be_instance_of RelatonIeee::IeeeBibliographicItem
   end
 
   it "get IHO reference" do