relaton 2.1.0 → 3.0.0.pre.alpha.1

data/.github/workflows/rake.yml

@@ -1,14 +0,0 @@
-# Auto-generated by Cimas: Do not edit it manually!
-# See https://github.com/metanorma/cimas
-name: rake
-
-on:
-  push:
-    branches: [ master, main ]
-    tags: [ v* ]
-  pull_request:
-  workflow_dispatch:
-
-jobs:
-  rake:
-    uses: relaton/support/.github/workflows/rake.yml@main

data/.github/workflows/release.yml

@@ -1,24 +0,0 @@
-# Auto-generated by Cimas: Do not edit it manually!
-# See https://github.com/metanorma/cimas
-name: release
-
-on:
-  workflow_dispatch:
-    inputs:
-      next_version:
-        description: |
-          Next release version. Possible values: x.y.z, major, minor, patch (or pre|rc|etc).
-          Also, you can pass 'skip' to skip 'git tag' and do 'gem push' for the current version
-        required: true
-        default: 'skip'
-  repository_dispatch:
-    types: [ do-release ]
-
-
-jobs:
-  release:
-    uses: relaton/support/.github/workflows/release.yml@main
-    with:
-      next_version: ${{ github.event.inputs.next_version }}
-    secrets:
-      rubygems-api-key: ${{ secrets.RELATON_CI_RUBYGEMS_API_KEY }}

data/.github/workflows/rubocop.yml

@@ -1,48 +0,0 @@
-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

@@ -1,12 +0,0 @@
-coverage/
-.byebug_history
-.rspec_status
-
-testcache
-testcache2
-.rubocop-https---raw-githubusercontent-com-riboseinc-oss-guides-master-ci-rubocop-yml
-.vscode/
-pkg/
-Gemfile.lock
-.rubocop-remote-87c7cdd254a8d09d005ee06efac7acc0.yml
-.claude/

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper

data/.rubocop.yml

@@ -1,12 +0,0 @@
-# This project follows the Ribose OSS style guide.
-# https://github.com/riboseinc/oss-guides
-# All project-specific additions and overrides should be specified in this file.
-
-plugins: rubocop-rails
-
-inherit_from:
-  - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
-AllCops:
-  TargetRubyVersion: 3.2
-Rails:
-  Enabled: false

data/CLAUDE.md

@@ -1,70 +0,0 @@
-# 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`, `from_yaml`, `grammar_hash`, `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
-
-`Relaton::Db#fetch_all(text, edition, year)` searches cached entries, filtering by text content (via `match_xml_text?`), edition, and/or year. Returns an array of deserialized bibliographic items from both local and global caches.
-
-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.2
-- Thread safety via `@semaphore` (Mutex) around cache reads/writes in Db

data/Gemfile

@@ -1,21 +0,0 @@
-source "https://rubygems.org"
-
-# Specify your gem's dependencies in gemspec
-gemspec
-
-
-
-gem "byebug"
-gem "equivalent-xml", "~> 0.6"
-gem "guard", "~> 2.14"
-gem "guard-rspec", "~> 4.7"
-gem "pry-byebug"
-gem "rake", "~> 13.0"
-gem "rspec", "~> 3.6"
-gem "rubocop"
-gem "rubocop-performance"
-gem "rubocop-rails"
-gem "simplecov", "~> 0.15"
-gem "timecop", "~> 0.9"
-gem "vcr", "~> 6"
-gem "webmock", "~> 3.18"

data/Rakefile

@@ -1,6 +0,0 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-task default: :spec

data/docs/CHANGELOG.adoc

@@ -1,16 +0,0 @@
-= Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on https://keepachangelog.com/en/1.0.0/[Keep a Changelog], and this project adheres to https://semver.org/[Semantic Versioning].
-
-== [Unreleased]
-
-== [1.19.2] - 2024-06-29
-- Lazy load Relaton flavor gems dependencies.
-
-== [1.19.1] - 2024-06-24
-- Add `relaton-plateau` flavor gem.
-
-== [1.19.0] - 2024-06-29
-- Switch to using the `relaton-logger` gem for logging.

data/docs/VERSIONING_POLICY.adoc

@@ -1,38 +0,0 @@
-= Versioning Policy
-
-This document describes the versioning policy for the Relaton project. We follow the https://semver.org/[Semantic Versioning] scheme.
-
-== Versioning Scheme
-
-Version nubmers are in the form of `MAJOR.MINOR.PATCH`. The version number is incremented based on the following:
-
-- `MAJOR` version is incremented when incompatible changes are made to the API.
-- `MINOR` version is incremented when the Relaton data model is changed.
-- `PATCH` version is incremented when backward-compatible bug fixes are made.
-
-== Rules for incrementing version numbers
-
-1. **MAJOR** version is incremented when incompatible changes are made to the API. Icrement the MAJOR version when:
-   - Removing or renaming classes or methods.
-   - Changing the signature of a method.
-   - Changing the behavior of a method.
-
-2. **MINOR** version is incremented when the Relaton data model is changed. Increment the MINOR version when:
-   - Adding, remmoving or renaming attributes of data model classes.
-   - Adding new data model classes.
-
-3. **PATCH** version is incremented when backward-compatible bug fixes are made. Increment the PATCH version when:
-   - Fixing a bug that does not change the behavior of the API.
-   - Improving the performance of the API.
-
-== Additional Guidelines
-
-For convenience, we use the same major and minor vesions for all the Relaton flavor gems that uses the same version of the Relaton data model.
-
-== Exceptions
-
-In some cases, we may increment the `PATCH` version for backward-incompatible changes. In such cases, we will update dependent gems to use the new version or higher. For example `"~> 1.19.2"` doen't allow to use version less than `1.19.2`.
-
-== References
-
-- https://semver.org/[Semantic Versioning]

data/docs/navigation.adoc

@@ -1,6 +0,0 @@
----
-items:
-  - { title: README, path: README/ }
----
-
-= Navigation

data/lib/relaton/config.rb

@@ -1,24 +0,0 @@
-module Relaton
-  module Config
-    def configure
-      yield configuration if block_given?
-    end
-
-    def configuration
-      @configuration ||= self::Configuration.new
-    end
-  end
-
-  # < RelatonBib::Configuration
-  class Configuration
-    attr_accessor :use_api, :api_host
-
-    def initialize
-      # super
-      @use_api = false
-      @api_host = "https://api.relaton.org"
-    end
-  end
-
-  extend Config
-end

data/lib/relaton/db_cache.rb

@@ -1,230 +0,0 @@
-require "fileutils"
-require "timeout"
-
-module Relaton
-  class DbCache
-    # @return [String]
-    attr_reader :dir
-
-    # @param dir [String] DB directory
-    def initialize(dir, ext = "xml")
-      @dir = dir
-      @ext = ext
-      FileUtils::mkdir_p dir
-    end
-
-    # Move caches to anothe dir
-    # @param new_dir [String, nil]
-    # @return [String, nil]
-    def mv(new_dir)
-      return unless new_dir && @ext == "xml"
-
-      if File.exist? new_dir
-        Util.info "target directory exists `#{new_dir}`"
-        return
-      end
-
-      FileUtils.mv dir, new_dir
-      @dir = new_dir
-    end
-
-    # Clear database
-    def clear
-      FileUtils.rm_rf Dir.glob "#{dir}/*"
-    end
-
-    # Save item
-    # @param key [String]
-    # @param value [String] Bibitem xml serialization
-    def []=(key, value)
-      if value.nil?
-        delete key
-        return
-      end
-
-      prefix_dir = "#{@dir}/#{prefix(key)}"
-      FileUtils::mkdir_p prefix_dir
-      set_version prefix_dir
-      file_safe_write "#{filename(key)}.#{ext(value)}", value
-    end
-
-    # @param value [String]
-    # @return [String]
-    def ext(value)
-      case value
-      when /^not_found/ then "notfound"
-      when /^redirection/ then "redirect"
-      else @ext
-      end
-    end
-
-    # Read item
-    # @param key [String]
-    # @return [String]
-    def [](key)
-      value = get(key)
-      if (code = redirect_code value)
-        self[code]
-      else
-        value
-      end
-    end
-
-    #
-    # Save entry from cache of `db` to this cache.
-    #
-    # @param [String] key key of the entry
-    # @param [Relaton::Db] db database
-    #
-    def clone_entry(key, db)
-      self[key] ||= db.get(key)
-      if (code = redirect_code get(key))
-        clone_entry code, db
-      end
-    end
-
-    # Return fetched date
-    # @param key [String]
-    # @return [String]
-    def fetched(key)
-      value = self[key]
-      return unless value
-
-      if value.match?(/^not_found/)
-        value.match(/\d{4}-\d{2}-\d{2}/).to_s
-      else
-        doc = Nokogiri::XML value
-        doc.at("/bibitem/fetched|bibdata/fetched")&.text
-      end
-    end
-
-    # Returns all items
-    # @return [Array<String>]
-    def all(&block)
-      Dir.glob("#{@dir}/**/*.{xml,yml,yaml}").map do |f|
-        content = File.read(f, encoding: "utf-8")
-        block ? yield(f, content) : content
-      end
-    end
-
-    # Delete item
-    # @param key [String]
-    def delete(key)
-      file = filename key
-      f = search_ext file
-      return unless f
-
-      if File.extname(f) == ".redirect"
-        code = redirect_code get(key)
-        delete code if code
-      end
-      File.delete f
-    end
-
-    # Check if version of the DB match to the gem grammar hash.
-    # @param fdir [String] dir pathe to flover cache
-    # @return [Boolean]
-    def check_version?(fdir)
-      version_dir = "#{fdir}/version"
-      return false unless File.exist? version_dir
-
-      v = File.read version_dir, encoding: "utf-8"
-      v.strip == self.class.grammar_hash(fdir)
-    end
-
-    # if cached reference is undated, expire it after 60 days
-    # @param key [String]
-    # @param year [String]
-    def valid_entry?(key, year)
-      datestr = fetched key
-      return false unless datestr
-
-      date = Date.parse datestr
-      year || Date.today - date < 60
-    end
-
-    # Reads file by a key
-    #
-    # @param key [String]
-    # @return [String, NilClass]
-    def get(key)
-      file = filename key
-      return unless (f = search_ext(file))
-
-      File.read(f, encoding: "utf-8")
-    end
-
-    # @param fdir [String] dir pathe to flover cache
-    # @return [String]
-    def self.grammar_hash(fdir)
-      type = fdir.split("/").last
-      Relaton::Registry.instance.by_type(type)&.grammar_hash
-    end
-
-    private
-
-    # @param value [String]
-    # @return [String]
-    def filename(key)
-      prefcode = key.downcase.match(/^(?<prefix>[^(]+)\((?<code>[^)]+)/)
-      fn = if prefcode
-             "#{prefcode[:prefix]}/#{prefcode[:code].gsub(/[:\s\/()]/,
-                                                          '_').squeeze('_')}"
-           else
-             key.gsub(/[-:\s]/, "_")
-           end
-      "#{@dir}/#{fn.sub(/(,|_$)/, '')}"
-    end
-
-    #
-    # Checks if there is file with xml or txt extension and return filename with
-    # the extension.
-    #
-    # @param file [String]
-    # @return [String, NilClass]
-    def search_ext(file)
-      if File.exist?("#{file}.#{@ext}")
-        "#{file}.#{@ext}"
-      elsif File.exist? "#{file}.notfound"
-        "#{file}.notfound"
-      elsif File.exist? "#{file}.redirect"
-        "#{file}.redirect"
-      end
-    end
-
-    # Set version of the DB to the gem grammar hash.
-    # @param fdir [String] dir pathe to flover cache
-    def set_version(fdir)
-      file_version = "#{fdir}/version"
-      unless File.exist? file_version
-        file_safe_write file_version, self.class.grammar_hash(fdir)
-      end
-    end
-
-    # Return item's file name
-    # @param key [String]
-    # @return [String]
-    def prefix(key)
-      key.downcase.match(/^[^(]+(?=\()/).to_s
-    end
-
-    # Check if a file content is redirection
-    #
-    # @prarm value [String] file content
-    # @return [String, NilClass] redirection code or nil
-    def redirect_code(value)
-      %r{redirection\s(?<code>.*)} =~ value
-      code
-    end
-
-    # @param file [String]
-    # @content [String]
-    def file_safe_write(file, content)
-      File.open file, File::RDWR | File::CREAT, encoding: "UTF-8" do |f|
-        Timeout.timeout(10) { f.flock File::LOCK_EX }
-        f.write content
-        f.flock File::LOCK_UN
-      end
-    end
-  end
-end

data/lib/relaton/registry.rb

@@ -1,118 +0,0 @@
-require "singleton"
-
-# class Error < StandardError
-# end
-
-module Relaton
-  class Registry
-    SUPPORTED_GEMS = %w[
-      relaton/gb relaton/iec relaton/ietf relaton/iso
-      relaton/itu relaton/nist relaton/ogc relaton/calconnect
-      relaton/omg relaton/un relaton/w3c relaton/ieee
-      relaton/iho relaton/bipm relaton/ecma relaton/cie
-      relaton/bsi relaton/cen relaton/iana relaton/3gpp
-      relaton/oasis relaton/doi relaton/jis relaton/xsf
-      relaton/ccsds relaton/etsi relaton/isbn relaton/plateau
-    ].freeze
-
-    include Singleton
-
-    attr_reader :processors
-
-    def initialize
-      @processors = {}
-      register_gems
-    end
-
-    def register_gems
-      # Util.info("Info: detecting backends:")
-
-      SUPPORTED_GEMS.each do |b|
-        require "#{b}/processor"
-        register Kernel.const_get "#{gem_to_module_path(b)}::Processor"
-      rescue LoadError => e
-        Util.error "backend #{b} not present\n" \
-                   "#{e.message}\n#{e.backtrace.join "\n"}"
-      end
-    end
-
-    def register(processor)
-      raise Error unless processor < Core::Processor
-
-      p = processor.new
-      return if processors[p.short]
-
-      Util.debug("processor \"#{p.short}\" registered")
-      processors[p.short] = p
-    end
-
-    def find_processor(short)
-      processors[short.to_sym]
-    end
-
-    # @return [Array<Symbol>]
-    def supported_processors
-      processors.keys
-    end
-
-    #
-    # Search a rpocessos by dataset name
-    #
-    # @param [String] dataset
-    #
-    # @return [Relaton::Core::Processor, nil]
-    #
-    def find_processor_by_dataset(dataset)
-      processors.values.detect { |p| p.datasets&.include? dataset }
-    end
-
-    #
-    # Find processor by type
-    #
-    # @param type [String]
-    # @return [Relaton::Core::Processor]
-    def by_type(type)
-      processors.values.detect { |v| v.prefix == type&.upcase }
-    end
-
-    def [](stdclass)
-      processors[stdclass]
-    end
-
-    #
-    # Find processor by reference or prefix
-    #
-    # @param [String] ref reference or prefix
-    #
-    # @return [Relaton::Core::Processor] processor
-    #
-    def processor_by_ref(ref)
-      processors[class_by_ref(ref)]
-    end
-
-    #
-    # Find processor by refernce or prefix
-    #
-    # @param ref [String] reference or prefix
-    #
-    # @return [Symbol, nil] standard class name
-    #
-    def class_by_ref(ref)
-      ref = Regexp.last_match(1) if ref =~ /^\w+\((.*)\)$/
-      @processors.each do |class_name, processor|
-        return class_name if /^(urn:)?#{processor.prefix}\b/i.match?(ref) ||
-          processor.defaultprefix.match(ref)
-      end
-      Util.info "`#{ref}` does not have a recognised prefix", key: ref
-      nil
-    end
-
-    private
-
-    def gem_to_module_path(gem_name)
-      gem_name.split("/").map do |part|
-        part.capitalize.sub("3gpp", "ThreeGpp")
-      end.join("::")
-    end
-  end
-end

data/lib/relaton/util.rb

@@ -1,7 +0,0 @@
-module Relaton
-  module Util
-    extend Relaton::Bib::Util
-
-    PROGNAME = "relaton".freeze
-  end
-end

data/lib/relaton/workers_pool.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-module Relaton
-  # Workers poll.
-  class WorkersPool
-    def initialize(workers = 2, &)
-      # num_workers = workers < 2 ? 2 : workers
-      @queue = SizedQueue.new(workers * 2)
-      @threads = Array.new workers do
-        Thread.new do
-          while item = @queue.pop; yield(item) end
-        end
-      end
-    end
-
-    def <<(item)
-      @queue << item
-      self
-    end
-  end
-end