relaton 3.0.0.pre.alpha.1 → 3.0.0.pre.alpha.2

data/lib/relaton/plateau/hit_collection.rb

@@ -5,14 +5,20 @@ module Relaton
     class HitCollection < Relaton::Core::HitCollection
       ENDPOINT = "https://raw.githubusercontent.com/relaton/relaton-data-plateau/v2/"
 
+      # An edition suffix in either the canonical Japanese form (`第1.0版`) or the
+      # legacy Latin form (`1.0`), stripped in #to_all_editions to derive the
+      # edition-less family id from a relaton-bib docidentifier *string* (the
+      # fetched document is not a pubid). Matching itself is done on pubid objects.
+      EDITION_SUFFIX = / (?:第[\d.]+版|\d+\.\d+)$/
+
+      # An edition-less reference selects every edition of the document with
+      # pubid's subset match `pubid_ref === row`: the omitted edition matches
+      # any value, and pubid declares `annex` strict for PLATEAU, so
+      # `PLATEAU Handbook #03` does not reach `#03-1`. A reference with an
+      # edition selects that one row with `==`.
       def find
-        @array = index.search do |row|
-          if all_editions?
-            row[:id].sub(/ \d+\.\d+$/, "") == @ref
-          else
-            row[:id] == @ref
-          end
-        end.map { |row| Hit.new(row, self) }
+        @array = index.search(pubid_ref, exact: !all_editions?)
+          .map { |row| Hit.new(row, self) }
         self
       end
 
@@ -24,14 +30,28 @@ module Relaton
 
       def index
         @index ||= Relaton::Index.find_or_create(
-          :plateau, url: "#{ENDPOINT}#{INDEXFILE}.zip", file: "#{INDEXFILE}.yaml"
+          :plateau, url: "#{ENDPOINT}#{INDEXFILE}.zip", file: "#{INDEXFILE}.yaml",
+          pubid_class: ::Pubid::Plateau::Identifier
         )
       end
 
       private
 
+      # `#ref` (the raw query string, from Core::HitCollection) parsed into a
+      # canonical Pubid::Plateau::Identifier (memoized). Canonical (`第1.0版`),
+      # edition-less (`#00`), and legacy Latin (`#00 1.0`) references all
+      # parse — pubid normalizes Latin input to the canonical id
+      # (metanorma/pubid #269) — so search accepts both forms. An unrecognized
+      # reference raises; like ISO and 3GPP we let it propagate — relaton-cli
+      # rescues Pubid::Errors::Error. See lib/relaton/plateau/CLAUDE.md.
+      def pubid_ref
+        @pubid_ref ||= ::Pubid::Plateau.parse(ref)
+      end
+
+      # A reference with no edition (`PLATEAU Handbook #00`, or any Technical
+      # Report — TRs carry no edition) asks for all editions of the document.
       def all_editions?
-        @ref.match?(/ #\d+$/)
+        pubid_ref.edition.nil?
       end
 
       def to_all_editions
@@ -43,12 +63,12 @@ module Relaton
         end
         docid = bibitem.docidentifier.map do |d|
           Bib::Docidentifier.new(
-            content: d.content.sub(/ \d+\.\d+$/, ""), type: d.type, primary: d.primary
+            content: d.content.sub(EDITION_SUFFIX, ""), type: d.type, primary: d.primary
           )
         end
         ItemData.new(
           docidentifier: docid,
-          docnumber: bibitem.docnumber.sub(/ \d+\.\d+$/, ""),
+          docnumber: bibitem.docnumber.sub(EDITION_SUFFIX, ""),
           title: bibitem.title,
           contributor: bibitem.contributor,
           relation: relations

data/lib/relaton/plateau/processor.rb

@@ -42,7 +42,9 @@ module Relaton
 
       def remove_index_file
         require_relative "../plateau"
-        Relaton::Index.find_or_create(:plateau, url: true, file: "#{INDEXFILE}.yaml").remove_file
+        Relaton::Index.find_or_create(
+          :plateau, url: true, file: "#{INDEXFILE}.yaml"
+        ).remove_file
       end
     end
   end

data/lib/relaton/plateau/technical_report_parser.rb

@@ -10,7 +10,14 @@ module Relaton
 
       def parse_docnumber
         @errors[:tr_docnumber] &&= @entry["slug"].nil? || @entry["slug"].to_s.empty?
-        "Technical Report ##{@entry["slug"]} #{edition_number}"
+        "Technical Report ##{canonical_slug}"
+      end
+
+      # Canonical sub-number separator is "-" (Pubid::Plateau); source slugs use
+      # "_" (e.g. "46_1" -> "46-1"). PLATEAU Technical Report ids carry no
+      # edition in canonical form, so #edition_number is not part of the id.
+      def canonical_slug
+        @entry["slug"].to_s.tr("_", "-")
       end
 
       def parse_abstract

data/lib/relaton/plateau.rb

@@ -1,5 +1,6 @@
 require "net/http"
 require "uri"
+require "pubid"
 require "relaton/index"
 require "relaton/iso"
 require_relative "version"
@@ -17,7 +18,7 @@ require_relative "plateau/processor"
 
 module Relaton
   module Plateau
-    INDEXFILE = "index-v1"
+    INDEXFILE = "index-v2"
 
     class Error < StandardError; end
 

data/lib/relaton/sdo/config.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Sdo
+    # Configuration for the SDO org/logo store: where the index manifest lives,
+    # where to cache it, and for how long. Mirrors Relaton::Index::Config; the
+    # storage backend is swappable (e.g. an S3-backed object) via `storage=`.
+    class Config
+      # Default published index of the relaton-data-sdo data repo.
+      DEFAULT_URL =
+        "https://raw.githubusercontent.com/relaton/relaton-data-sdo/main/index.yaml"
+
+      attr_accessor :url, :storage, :storage_dir, :ttl
+
+      def initialize
+        @url = DEFAULT_URL
+        @storage = Relaton::Index::FileStorage
+        @storage_dir = File.join(Dir.home, ".relaton", "sdo")
+        @ttl = 24 * 60 * 60 # seconds
+      end
+    end
+
+    class << self
+      def configuration
+        @configuration ||= Config.new
+      end
+
+      def configure
+        yield configuration if block_given?
+        configuration
+      end
+    end
+  end
+end

data/lib/relaton/sdo/fetcher.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Sdo
+    # Download helper. The index manifest is text-cached under the configured
+    # storage dir with a TTL (reusing Relaton::Index::FileStorage); logo binaries
+    # are fetched on demand and left to in-process memoization on the Logo.
+    module Fetcher
+      module_function
+
+      # Fetch the index manifest, serving a fresh on-disk copy when present and
+      # falling back to a stale cache if the network fetch fails.
+      def fetch_index
+        config = Sdo.configuration
+        cache = File.join(config.storage_dir, "index.yaml")
+
+        if fresh?(cache, config)
+          cached = config.storage.read(cache)
+          return cached if cached
+        end
+
+        data = download(config.url)
+        return config.storage.read(cache) if data.nil? # stale cache or nil
+
+        config.storage.write(cache, data)
+        data
+      end
+
+      # GET a URL and return the body, or nil on failure. A URL with no scheme
+      # (or a file:// URL) is read straight off disk — handy for local fixtures.
+      def download(url)
+        uri = url.is_a?(URI) ? url : URI.parse(url.to_s)
+        return read_file(uri, url) if uri.scheme.nil? || uri.scheme == "file"
+
+        response = Net::HTTP.get_response(uri)
+        response.is_a?(Net::HTTPSuccess) ? response.body : nil
+      rescue StandardError
+        nil
+      end
+
+      def fresh?(file, config)
+        ctime = config.storage.ctime(file)
+        ctime && (Time.now - ctime) < config.ttl
+      end
+
+      def read_file(uri, url)
+        path = uri.path.to_s.empty? ? url.to_s : uri.path
+        File.exist?(path) ? File.binread(path) : nil
+      end
+    end
+  end
+end

data/lib/relaton/sdo/logo.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Sdo
+    # One logo variant for an organization. Variants are differentiated by
+    # `style` (the primary discriminator — e.g. "default", "red", "iso_1972"),
+    # `format` (file suffix) and `size`. `applicability` is opaque, informational
+    # text (e.g. "stage>=60"); the store never interprets it — consumers do.
+    class Logo
+      MIME_TYPES = {
+        "png" => "image/png",
+        "jpg" => "image/jpeg",
+        "jpeg" => "image/jpeg",
+        "gif" => "image/gif",
+        "svg" => "image/svg+xml",
+        "webp" => "image/webp",
+        "eps" => "application/postscript",
+        "pdf" => "application/pdf",
+      }.freeze
+
+      attr_reader :style, :format, :size, :url, :applicability
+
+      def initialize(style: nil, format: nil, size: nil, url: nil, applicability: nil)
+        @style = style
+        @format = format
+        @size = size
+        @url = url
+        @applicability = applicability
+      end
+
+      def self.from_hash(hash)
+        new(style: hash["style"], format: hash["format"], size: hash["size"],
+            url: hash["url"], applicability: hash["applicability"])
+      end
+
+      # Raw binary content of the logo, fetched lazily from `url` and memoized.
+      # Raises Sdo::Error (naming the URL) if the fetch fails, rather than
+      # returning nil and crashing cryptically inside data_uri/save downstream.
+      def content
+        @content ||= begin
+          data = Fetcher.download(url)
+          raise Error, "could not fetch logo from #{url.inspect}" if data.nil?
+
+          data
+        end
+      end
+
+      # The logo as a base64-encoded data URI, ready to embed in XML/HTML.
+      def data_uri
+        "data:#{mimetype};base64,#{Base64.strict_encode64(content)}"
+      end
+
+      def mimetype
+        MIME_TYPES[format.to_s.downcase] || "application/octet-stream"
+      end
+
+      # Write the logo to disk. With no argument, uses a filename derived from
+      # the source URL (or from style/size/format); returns the path written.
+      def save(path = nil)
+        path ||= default_filename
+        File.binwrite(path, content)
+        path
+      end
+
+      def to_h
+        { style: style, format: format, size: size, url: url,
+          applicability: applicability }.compact
+      end
+
+      def describe
+        to_h.map { |k, v| "#{k}=#{v}" }.join(", ")
+      end
+
+      private
+
+      def default_filename
+        base = File.basename(url_path)
+        return base unless base.empty? || File.extname(base).empty?
+
+        stem = [style, size].reject { |s| s.to_s.empty? }.join("-")
+        stem = "logo" if stem.empty?
+        ext = format.to_s.empty? ? "bin" : format
+        "#{stem}.#{ext}"
+      end
+
+      # The URL's path component, tolerating URLs that URI can't parse (e.g. a
+      # stray space) by falling back to the raw string sans query/fragment.
+      def url_path
+        URI.parse(url.to_s).path
+      rescue URI::InvalidURIError
+        url.to_s.split(/[?#]/, 2).first
+      end
+    end
+  end
+end

data/lib/relaton/sdo/name.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Sdo
+    # A single organization name, optionally tagged with a language. A name with
+    # no language is the default (untranslated) name.
+    class Name
+      attr_reader :content, :language
+
+      def initialize(content:, language: nil)
+        @content = content
+        @language = language
+      end
+
+      def self.from_hash(hash)
+        return new(content: hash) unless hash.is_a?(Hash)
+
+        new(content: hash["content"], language: hash["language"])
+      end
+
+      def default?
+        language.nil? || language.to_s.empty?
+      end
+    end
+  end
+end

data/lib/relaton/sdo/organization.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Sdo
+    # A standards-development organization: its names (with translations) and its
+    # logo variants. Built from one entry of the index manifest.
+    class Organization
+      attr_reader :abbreviation, :names, :logos
+
+      def initialize(abbreviation:, names: [], logos: [])
+        @abbreviation = abbreviation
+        @names = names
+        @logos = logos
+      end
+
+      def self.from_hash(abbreviation, hash)
+        hash ||= {}
+        new(
+          abbreviation: abbreviation,
+          names: Array(hash["name"]).map { |n| Name.from_hash(n) },
+          logos: Array(hash["logo"]).map { |l| Logo.from_hash(l) },
+        )
+      end
+
+      # The organization's name. With no argument (or a nil language) returns the
+      # default, untranslated name; otherwise the translation for the requested
+      # language — passed positionally (`name("fr")`) or as the `language:`
+      # keyword (`name(language: "fr")`) — or nil if there is none. The keyword
+      # wins if both are given.
+      def name(lang = nil, language: nil)
+        language ||= lang
+        selected =
+          if language.nil?
+            names.find(&:default?) || names.first
+          else
+            names.find { |n| n.language == language }
+          end
+        selected&.content
+      end
+
+      # All logo variants matching the given filters. Every argument is optional;
+      # omitting one matches any value for it. Returns an array (possibly empty).
+      def logo_query(format: nil, size: nil, style: nil)
+        logos.select do |logo|
+          match?(logo.format, format) &&
+            match?(logo.size, size) &&
+            match?(logo.style, style)
+        end
+      end
+
+      # A single logo matching the filters. Returns nil when nothing matches; the
+      # sole match when exactly one does; raises when the filter is ambiguous so
+      # the caller narrows it by format/size/style.
+      def logo(format: nil, size: nil, style: nil)
+        matches = logo_query(format: format, size: size, style: style)
+        return matches.first if matches.size <= 1
+
+        raise Error, "#{matches.size} logos match #{abbreviation}; narrow by " \
+                     "format/size/style: #{matches.map(&:describe).join('; ')}"
+      end
+
+      private
+
+      def match?(value, query)
+        return true if query.nil?
+
+        !value.nil? && value.to_s.casecmp?(query.to_s)
+      end
+    end
+  end
+end

data/lib/relaton/sdo/store.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Relaton
+  module Sdo
+    # Singleton registry of organizations, built lazily from the index manifest
+    # and memoized for the process. `reset!` drops the memo (mainly for specs).
+    class Store
+      include Singleton
+
+      def initialize
+        @mutex = Mutex.new
+      end
+
+      # Look up an organization by abbreviation (case-insensitive). Returns an
+      # Organization or nil.
+      def organization(abbreviation)
+        index[normalize(abbreviation)]
+      end
+
+      # Lazily built and memoized; the mutex keeps a concurrent first access from
+      # downloading/parsing the index twice.
+      def index
+        @index || @mutex.synchronize { @index ||= build_index }
+      end
+
+      def reset!
+        @mutex.synchronize { @index = nil }
+      end
+
+      private
+
+      def normalize(abbreviation)
+        abbreviation.to_s.strip.upcase
+      end
+
+      def build_index
+        yaml = Fetcher.fetch_index
+        data = yaml.nil? || yaml.empty? ? {} : YAML.safe_load(yaml)
+        # A corrupt/unexpected index (non-mapping YAML) degrades to "no orgs"
+        # rather than crashing every lookup with a TypeError.
+        organizations = data.is_a?(Hash) ? (data["organizations"] || {}) : {}
+        organizations.each_with_object({}) do |(abbreviation, attrs), acc|
+          acc[normalize(abbreviation)] =
+            Organization.from_hash(abbreviation, attrs)
+        end
+      end
+    end
+  end
+end

data/lib/relaton/sdo.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Relaton::Sdo — the standards-body organization & logo store (metanorma#346,
+# relaton-db#132). A NON-flavor, lazily-autoloaded top-level component: it has
+# no processor and no Db::Registry entry. It fetches a small `index.yaml`
+# manifest published by the `relaton-data-sdo` data repo, caches it under
+# `~/.relaton/sdo/`, and exposes org names/translations and logo variants
+# (differentiated by style/format/size) via `Relaton.organization`.
+
+require "net/http"
+require "uri"
+require "yaml"
+require "base64"
+require "fileutils"
+require "singleton"
+
+require_relative "index/file_storage"
+require_relative "sdo/config"
+require_relative "sdo/name"
+require_relative "sdo/logo"
+require_relative "sdo/organization"
+require_relative "sdo/fetcher"
+require_relative "sdo/store"
+
+module Relaton
+  module Sdo
+    class Error < StandardError; end
+  end
+end

data/lib/relaton/version.rb

@@ -1,3 +1,3 @@
 module Relaton
-  VERSION = "3.0.0.pre.alpha.1".freeze
+  VERSION = "3.0.0.pre.alpha.2".freeze
 end

data/lib/relaton/w3c/bibliography.rb

@@ -2,23 +2,26 @@
 
 require "net/http"
 require "relaton/bib/hash_parser_v1"
-require_relative "pubid"
 
 module Relaton
   module W3c
     # Class methods for search W3C standards.
     class Bibliography
       SOURCE = "https://raw.githubusercontent.com/relaton/relaton-data-w3c/v2/"
+      # The Pages site of the data repo: it serves the machine index (manifest
+      # and shards) that `#index` reads. The documents still come from SOURCE.
+      PAGES_URL = "https://relaton.github.io/relaton-data-w3c/"
 
       class << self
-        # @param text [String]
+        # @param ref [String, Pubid::W3c::Identifier] a reference, or one
+        #   already parsed (relaton#189: `Relaton::Db` parses it once)
         # @return [Relaton::W3c::ItemData]
-        def search(text) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
-          pubid = PubId.parse text.sub(/^W3C\s/, "")
-          index = Relaton::Index.find_or_create(
-            :W3C, url: "#{SOURCE}#{INDEXFILE}.zip", file: "#{INDEXFILE}.yaml", id_keys: PubId::PARTS,
-          )
-          row = index.search { |r| pubid == r[:id] }.sort_by { |r| (r[:id][:date] || r[:id][:year]).to_i }.last
+        def search(ref)
+          # A reference pubid rejects raises `Pubid::Errors::ParseError`, which
+          # the transport rescue below does not catch.
+          pubid = ref.is_a?(::Pubid::W3c::Identifier) ? ref : parse_ref(ref)
+
+          row = best_match pubid
           return unless row
 
           url = "#{SOURCE}#{row[:file]}"
@@ -32,20 +35,137 @@ module Relaton
           raise Relaton::RequestError, "Could not access #{url}: #{e.message}"
         end
 
-        # @param ref [String] the W3C standard Code to look up
+        #
+        # Find the index row for a reference, newest edition first.
+        #
+        # Passing the pubid to `Index::Type#search` is what enables the binary
+        # search on `id.root.number` — with a block alone the whole index is
+        # scanned. Selection is `Type#search`'s default with no block — pubid's
+        # asymmetric subset match (`Pubid::SubsetMatch`): the reference on the
+        # left, the row on the right, and a component it omits matches any
+        # value. `date`
+        # is W3C's only optional component, so an undated `REC-xml-names` still
+        # finds the dated row, while a dated reference reaches only its own.
+        # The maturity level is deliberately NOT a wildcard: it is the
+        # identifier's class, and `===` requires the same class, so `WD-`,
+        # `REC-` and a bare slug never match each other — the same contract the
+        # bespoke `PubId#==` had for its `stage`/`type`.
+        #
+        # @param pubid [Pubid::W3c::Identifier]
+        # @return [Hash, nil]
+        #
+        def best_match(pubid)
+          rows = index.search(pubid)
+          rows = index.search { |r| loose_match? r[:id], pubid } if rows.empty?
+
+          # Newest edition wins. Undated rows all score 0, so the file path
+          # breaks the tie and a repeated lookup returns the same document
+          # (the index sort is not stable).
+          rows.max_by { |r| [date_key(r[:id].date), r[:file]] }
+        end
+
+        #
+        # Order key for a W3C publication date.
+        #
+        # The dates are opaque digit runs of varying width, so a plain `to_i`
+        # does not order them: a legacy 6-digit `YYMMDD` always loses to an
+        # 8-digit `YYYYMMDD`, however much later it is (`980619` is June 1998,
+        # `19980512` is May). Restoring the century fixes that — all 63
+        # 6-digit dates in the corpus are 1990s.
+        #
+        # Everything else keeps `to_i`, deliberately. The 21 legacy 4-digit
+        # `MMDD` dates carry no year and cannot be ordered against a real one
+        # at all; as small integers they land below every dated row and above
+        # an undated one, which is where `to_i` already put them.
+        #
+        # @param date [String, nil]
+        # @return [Integer]
+        #
+        def date_key(date)
+          str = date.to_s
+          str.length == 6 ? "19#{str}".to_i : str.to_i
+        end
+
+        #
+        # The narrowed range cannot serve a reference whose slug differs from
+        # the row's only by case: the bsearch key is case-sensitive. The
+        # bespoke `PubId#==` compared its `code` with `casecmp?`, so a full
+        # scan repeats the match case-insensitively rather than lose that.
+        # (The BIPM `search_index` precedent.)
+        #
+        # @param row_id [Pubid::W3c::Identifier]
+        # @param pubid [Pubid::W3c::Identifier]
+        # @return [Boolean]
+        #
+        def loose_match?(row_id, pubid)
+          row_id.instance_of?(pubid.class) &&
+            row_id.number.to_s.casecmp?(pubid.number.to_s) &&
+            (pubid.date.nil? || row_id.date == pubid.date)
+        end
+
+        #
+        # The machine index on the Pages site (relaton#189, W3C is the pilot).
+        # A parsed query reads only its own shard; the whole index is read, in
+        # memory, only by the case-insensitive fallback in `#best_match`.
+        # A Pages failure raises `Relaton::RequestError`, with no fallback to
+        # the `index-v2.zip` in the data repo.
+        #
+        def index
+          Relaton::Index.find_or_create(
+            :W3C, pages_url: PAGES_URL, pubid_class: ::Pubid::W3c::Identifier
+          )
+        end
+
+        #
+        # Parse a user reference into a `Pubid::W3c::Identifier`, or nil.
+        #
+        # A search string is a query, not a document identifier field, so it
+        # does not go through `Docidentifier`: it has to absorb two forms the
+        # bespoke regex accepted and a pubid grammar should not. A URL is not
+        # an identifier (`https://www.w3.org/TR/xml-names/`), and `TR` is a
+        # path segment of that URL rather than a maturity level, so
+        # `TR-vocab-adms` means the document `vocab-adms`. The publisher
+        # prefix is added when absent, because `Pubid::W3c` requires it.
+        #
+        # @param text [String]
+        # @return [Pubid::W3c::Identifier, nil]
+        #
+        # An unrecognized reference **raises**; like ISO, ETSI and 3GPP we let it
+        # propagate. relaton-cli rescues `Pubid::Errors::Error` and renders
+        # `"..." is not a recognized standards identifier`
+        # (`gems/relaton-cli/lib/relaton/cli/command.rb:324`), and `Db#fetch`
+        # logs it through the `StandardError` arm at `lib/relaton/db.rb:122`.
+        # Rescuing here would collapse "this identifier is malformed" into "no
+        # such document", leaving a caller unable to tell them apart.
+        def parse_ref(text)
+          ::Pubid::W3c::Identifier.parse normalize_ref(text)
+        end
+
+        def normalize_ref(text)
+          ref = text.to_s.strip
+            .sub(%r{\Ahttps?://[^/]+/}i, "") # a URL is not an identifier
+            .sub(/\AW3C\s+/i, "")
+            .sub(%r{\ATR[/-]}i, "")          # URL path segment, not a stage
+            .sub(%r{/\z}, "")
+          "W3C #{ref}"
+        end
+
+        # @param ref [String, Pubid::W3c::Identifier] the W3C standard Code
+        #   to look up, or its parsed identifier
         # @param year [String, NilClass] not used
         # @param opts [Hash] options
         # @return [Relaton::W3c::ItemData]
         def get(ref, _year = nil, _opts = {})
-          Util.info "Fetching from Relaton repository ...", key: ref
+          key = ref.to_s
+          Util.info "Fetching from Relaton repository ...", key: key
           result = search(ref)
           unless result
-            Util.info "Not found.", key: ref
+            Util.info "Not found.", key: key
             return
           end
 
           found = result.docidentifier.first.content
-          Util.info "Found: `#{found}`", key: ref
+          Util.info "Found: `#{found}`", key: key
           result
         end
       end