relaton-cli 1.20.5 → 1.20.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9532812554990a4cc11d27d32a940db3ae908343c7154de1268deec1cefa55fb
-  data.tar.gz: 4bcfe71b907f013cee3e4f07751083016b23321cad540b1340f323051927946c
+  metadata.gz: 7ff8803a958b14fe70492cc25af28bfa118794bccc3228ae36212123209c2ab0
+  data.tar.gz: db4c4530d596210a187b2ddd2f750fef9c19cc10a07c7f19ecd8ab663485ad05
 SHA512:
-  metadata.gz: f1679a4108b0bdb582b3ce78dd5eb8b13ee5e08194d9906e529e15ed394cc6d0d8a0f82ca53c6700d7cbe2e5137a6d86bb9c0356ee5b5ed004acd04c2f751d32
-  data.tar.gz: 6e5051f654b4c48a8c9d08ca5a4e95e0960bfb893711dae1d124463f1dd5da251d7ffe70acf51bd9895cd5c986a74e6d122d4fb518670c47ad57a84f8ea40e6f
+  metadata.gz: 1f577e86bfc2f730ada8e74220dc37523837b0e6d286df337a4a1e5bb33501cbbcf783867c27fad946f1726c727ccbbf1493116ac6c8957b5031ac06792eeaed
+  data.tar.gz: c4ac8ee7cc37f9ac217d451a34bcee4bee6b4efe7036e92c160db6dd30d88b1f845ccb07d27f53a8b6e5a597663683f5537e3e1d85bde8942ac336f0c2128df3

data/.gitignore

@@ -15,3 +15,4 @@
 .byebug_history
 Gemfile.lock
 .DS_Store
+.claude/

data/CLAUDE.md

@@ -0,0 +1,96 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+relaton-cli is a Ruby CLI tool for managing bibliographic references to standards (ISO, IEC, IETF, NIST, etc.). It provides commands to fetch, convert, and organize standards metadata in XML, YAML, BibTeX, and HTML formats. Part of the broader Relaton/Metanorma ecosystem.
+
+## Common Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run all tests
+bundle exec rspec
+
+# Run a single test file
+bundle exec rspec spec/relaton/cli/command_spec.rb
+
+# Run a specific test by line number
+bundle exec rspec spec/relaton/cli/command_spec.rb:42
+
+# Build the gem
+bundle exec rake build
+
+# Lint (RuboCop, inherits from Ribose OSS guide)
+bundle exec rubocop
+bundle exec rubocop -a  # auto-fix
+```
+
+## Architecture
+
+### Entry Point & CLI Framework
+
+The executable `exe/relaton` calls `Relaton::Cli.start(ARGV)` which routes to `Relaton::Cli::Command`, a Thor-based command class. Thor handles argument parsing, option definitions, and subcommand routing.
+
+### Command Structure
+
+- `lib/relaton/cli/command.rb` — Main Thor command class with top-level commands (fetch, extract, concatenate, split, yaml2xml, xml2yaml, xml2html, yaml2html, convert, fetch-data)
+- `lib/relaton/cli/subcommand_collection.rb` — `relaton collection` subcommands (create, info, list, get, find, fetch, import, export)
+- `lib/relaton/cli/subcommand_db.rb` — `relaton db` subcommands (create, mv, clear, fetch, fetch_all, doctype)
+
+### Option Forwarding Pattern
+
+`Command#fetch` and `SubcommandDb#fetch` use the shared `fetch_document` helper (in `Relaton::Cli` private methods at the bottom of `command.rb`). This helper transforms Thor's kebab-case option keys to snake_case symbols via `gsub("-", "_").to_sym` and splats them as `**dup_opts` to `Relaton.db.fetch` / `Relaton.db.fetch_std`. Adding a new Thor option to these commands automatically forwards it to the underlying library with no method changes needed.
+
+`SubcommandCollection#fetch` calls `Relaton.db.fetch` directly (not through `fetch_document`), so new options must be explicitly forwarded there.
+
+Current fetch options that use this pattern: `--no-cache`, `--all-parts`, `--keep-year`, `--publication-date-before`, `--publication-date-after`.
+
+### Core Data Classes
+
+- `lib/relaton/bibdata.rb` — `Relaton::Bibdata` wraps `RelatonBib::BibliographicItem`, adding URL type handling and serialization to XML/YAML/Hash. Uses `method_missing` to delegate to the underlying bibitem.
+- `lib/relaton/bibcollection.rb` — `Relaton::Bibcollection` represents a collection of bibliographic items with title/author/doctype metadata. Handles XML/YAML round-tripping.
+- `lib/relaton/element_finder.rb` — Mixin providing XPath utilities with namespace handling.
+
+### Converters (Template Method Pattern)
+
+- `lib/relaton/cli/base_convertor.rb` — Abstract base defining the conversion flow (convert_and_write, write_to_file_collection)
+- `lib/relaton/cli/xml_convertor.rb` — XML → YAML conversion
+- `lib/relaton/cli/yaml_convertor.rb` — YAML → XML conversion (includes processor detection via doctype)
+- `lib/relaton/cli/xml_to_html_renderer.rb` — Renders XML/YAML to HTML using Liquid templates from `templates/`
+
+### File Operations
+
+`lib/relaton/cli/relaton_file.rb` — Static methods for extract (pull bibdata from Metanorma XML), concatenate (combine files into a collection), and split (break a collection into individual files).
+
+### Database (Singleton)
+
+`Relaton::Cli::RelatonDb` (in `lib/relaton/cli.rb`) is a Singleton managing a `Relaton::Db` instance. DB path is persisted in `~/.relaton/dbpath`. The `relaton` gem's registry auto-discovers 30+ standard-body processors.
+
+### Processor Detection
+
+`Relaton::Cli.processor(doc)` and `.parse_xml(doc)` detect the correct processor (ISO, IEC, IETF, etc.) from a document's `docidentifier` element type attribute, falling back to prefix matching.
+
+## Test Structure
+
+- `spec/acceptance/` — End-to-end CLI integration tests using `rspec-command`
+- `spec/relaton/cli/` — Unit tests for command, converters, subcommands, DB
+- `spec/relaton/` — Unit tests for Bibcollection and Bibdata
+- `spec/support/` — Test setup: SimpleCov, WebMock, VCR, equivalent-xml matchers
+- `spec/fixtures/` and `spec/vcr_cassettes/` — Test data and recorded HTTP responses
+
+Tests use VCR cassettes to replay HTTP interactions with standards registries. WebMock blocks real HTTP requests in tests.
+
+## Key Dependencies
+
+- `relaton ~> 1.20.0` — Core library providing DB, registry, and all standard-body processors
+- `thor` / `thor-hollaback` — CLI framework
+- `liquid ~> 5` — HTML template rendering
+- `nokogiri` (transitive via relaton) — XML parsing
+
+## Ruby Version
+
+Requires Ruby >= 3.0.0 (set in gemspec and `.rubocop.yml`).

data/docs/README.adoc

@@ -42,7 +42,7 @@ suports an additional `-x` or `--extension` options to use different extension.
 
 [source,console]
 ----
-$ relaton fetch CODE -t TYPE -f FORMAT -y YEAR -r RETRIES --all-parts --keep-year --no-cache
+$ relaton fetch CODE -t TYPE -f FORMAT -y YEAR -r RETRIES --all-parts --keep-year --no-cache --publication-date-before DATE --publication-date-after DATE
 ----
 
 Fetch the Relaton XML entry corresponding to the document identifier `CODE`.
@@ -54,6 +54,8 @@ Fetch the Relaton XML entry corresponding to the document identifier `CODE`.
 * `--all-parts` fetch all parts.
 * `--keep-year` undated reference should return an actual reference with year.
 * `--no-cache` do not use cache.
+* `--publication-date-before DATE` fetch only documents published before the specified date. Accepted formats: `YYYY`, `YYYY-MM`, `YYYY-MM-DD`.
+* `--publication-date-after DATE` fetch only documents published after the specified date. Accepted formats: `YYYY`, `YYYY-MM`, `YYYY-MM-DD`.
 
 === relaton fetch-data
 
@@ -358,7 +360,7 @@ Full-text search through a collection or all collections.
 ==== relaton collection fetch
 
 ----
-$ relaton collection fetch CODE -t TYPE -y YEAR -c COLLECTION -d DIRECTORY
+$ relaton collection fetch CODE -t TYPE -y YEAR -c COLLECTION -d DIRECTORY --publication-date-before DATE --publication-date-after DATE
 ----
 
 Fetch the Relaton XML entry corresponding to the document identifier `CODE` and save it into `COLLECTION`.
@@ -367,6 +369,8 @@ Fetch the Relaton XML entry corresponding to the document identifier `CODE` and
 * `YEAR` is optional, and specifies the year of publication of the standard.
 * `COLLECTION` - a name of a collection.
 * `DIRECTORY` - optional, and specifies a path to a directory with collections. The default value is `$HOME/.relaton/collections`.
+* `--publication-date-before DATE` fetch only documents published before the specified date. Accepted formats: `YYYY`, `YYYY-MM`, `YYYY-MM-DD`.
+* `--publication-date-after DATE` fetch only documents published after the specified date. Accepted formats: `YYYY`, `YYYY-MM`, `YYYY-MM-DD`.
 
 ==== relaton collection export
 

data/lib/relaton/cli/command.rb

@@ -1,3 +1,4 @@
+require "date"
 require "relaton/cli/relaton_file"
 require "relaton/cli/xml_convertor"
 require "relaton/cli/yaml_convertor"
@@ -31,6 +32,12 @@ module Relaton
       option :retries, aliases: :r, type: :numeric,
                        desc: "Number of network retries. Default 1."
       option :"no-cache", type: :boolean, desc: "Ignore cache"
+      option :"publication-date-before",
+        desc: "Fetch only documents published before the specified date " \
+          "(e.g. 2008, 2008-02, or 2008-02-02)"
+      option :"publication-date-after",
+        desc: "Fetch only documents published after the specified date " \
+          "(e.g. 2002, 2002-01, or 2002-01-01)"
 
       def fetch(code)
         io = IO.new($stdout.fcntl(::Fcntl::F_DUPFD), mode: "w:UTF-8")
@@ -174,6 +181,30 @@ module Relaton
 
     private
 
+    DATE_FILTER_FORMAT = /\A\d{4}(-\d{2}(-\d{2})?)?\z/
+
+    def parse_date_option(value, name)
+      return unless value
+
+      unless value.match?(DATE_FILTER_FORMAT)
+        raise ArgumentError,
+          "Invalid #{name}: #{value.inspect}. Expected YYYY, YYYY-MM, or YYYY-MM-DD."
+      end
+      parts = value.split("-").map(&:to_i)
+      Date.new(*parts.concat([1] * (3 - parts.size)))
+    rescue Date::Error
+      raise ArgumentError,
+        "Invalid #{name}: #{value.inspect}. Date components are out of range."
+    end
+
+    def validate_date_range(date_after, date_before)
+      return unless date_after && date_before
+      return if date_after < date_before
+
+      raise ArgumentError,
+        "Invalid date range: --publication-date-after (#{date_after}) must be before --publication-date-before (#{date_before})."
+    end
+
     # @param code [String]
     # @param options [Hash]
     # @option options [String] :type
@@ -183,6 +214,10 @@ module Relaton
     def fetch_document(code, options) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity,Metrics/AbcSize,Metrics/MethodLength
       year = options[:year]&.to_s
       dup_opts = options.dup.transform_keys { |k| k.to_s.gsub("-", "_").to_sym }
+      %i[publication_date_before publication_date_after].each do |key|
+        dup_opts[key] = parse_date_option(dup_opts[key], key.to_s.tr("_", "-").prepend("--")) if dup_opts[key]
+      end
+      validate_date_range dup_opts[:publication_date_after], dup_opts[:publication_date_before]
       if (processor = Relaton::Registry.instance.by_type options[:type]&.upcase)
         doc = Relaton.db.fetch_std code, year, processor.short, **dup_opts
       elsif options[:type] then return

data/lib/relaton/cli/subcommand_collection.rb

@@ -102,13 +102,27 @@ module Relaton
                     desc: "Type of standard to get bibliographic entry for"
       option :year, aliases: :y, type: :numeric,
                     desc: "Year the standard was published"
+      option :"publication-date-before",
+        desc: "Fetch only documents published before the specified date " \
+          "(e.g. 2008, 2008-02, or 2008-02-02)"
+      option :"publication-date-after",
+        desc: "Fetch only documents published after the specified date " \
+          "(e.g. 2002, 2002-01, or 2002-01-01)"
       option :collection, aliases: :c, required: true,
                           desc: "Collection to store a document"
       option :dir, aliases: :d, desc: "Directory with collections. Default is " \
                                       "$HOME/.relaton/collections."
 
       def fetch(code) # rubocop:disable Metrics/AbcSize
-        doc = Relaton.db.fetch(code, options[:year]&.to_s)
+        opts = {}
+        if options[:"publication-date-before"]
+          opts[:publication_date_before] = parse_date_option(options[:"publication-date-before"], "--publication-date-before")
+        end
+        if options[:"publication-date-after"]
+          opts[:publication_date_after] = parse_date_option(options[:"publication-date-after"], "--publication-date-after")
+        end
+        validate_date_range opts[:publication_date_after], opts[:publication_date_before]
+        doc = Relaton.db.fetch(code, options[:year]&.to_s, **opts)
         if doc
           colfile = File.join directory, options[:collection]
           coll = read_collection colfile

data/lib/relaton/cli/subcommand_db.rb

@@ -40,6 +40,12 @@ module Relaton
                                          "Default xml."
       option :year, aliases: :y, type: :numeric, desc: "Year the standard " \
                                                        "was published"
+      option :"publication-date-before",
+        desc: "Fetch only documents published before the specified date " \
+          "(e.g. 2008, 2008-02, or 2008-02-02)"
+      option :"publication-date-after",
+        desc: "Fetch only documents published after the specified date " \
+         "(e.g. 2002, 2002-01, or 2002-01-01)"
 
       def fetch(code)
         io = IO.new($stdout.fcntl(::Fcntl::F_DUPFD), mode: "w:UTF-8")

data/lib/relaton/cli/version.rb

@@ -1,5 +1,5 @@
 module Relaton
   module Cli
-    VERSION = "1.20.5".freeze
+    VERSION = "1.20.6".freeze
   end
 end

data/relaton-cli.gemspec

@@ -23,7 +23,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 3.0.0"
 
   spec.add_runtime_dependency "liquid", "~> 5"
-  spec.add_runtime_dependency "relaton", "~> 1.20.0"
+  spec.add_runtime_dependency "relaton", "~> 1.20.2"
   spec.add_runtime_dependency "thor"
   spec.add_runtime_dependency "thor-hollaback"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: relaton-cli
 version: !ruby/object:Gem::Version
-  version: 1.20.5
+  version: 1.20.6
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-24 00:00:00.000000000 Z
+date: 2026-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: liquid
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.20.0
+        version: 1.20.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.20.0
+        version: 1.20.2
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -97,6 +97,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - Gemfile
 - LICENSE
 - Rakefile