sec_id 5.1.0 → 6.0.0

data/lib/sec_id/active_model.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require 'sec_id'
+
+begin
+  require 'active_model'
+rescue LoadError => e
+  # :nocov: ActiveModel is always loadable in the test suite
+  raise LoadError, 'sec_id/active_model requires ActiveModel, which could not be loaded. Add ' \
+                   '`gem "activemodel"` to your Gemfile (or use this inside a Rails app) before ' \
+                   "requiring 'sec_id/active_model'. (#{e.message})"
+  # :nocov:
+end
+
+# ActiveModel validator for securities identifiers, registered under the `sec_id` key.
+#
+# It validates a value against a single type (`type:`), an allowlist (`types:`), or any of the
+# supported identifier types (no key). Validation is strict by default; separator-lenient
+# canonicalization and specific failure reasons are opt-in via `normalize:` and `details:`.
+#
+# This file is loaded automatically inside Rails (via {SecID::Railtie}) and must be required
+# explicitly (`require 'sec_id/active_model'`) in non-Rails ActiveModel stacks. It is never on
+# the default `require 'sec_id'` path, so the gem keeps its zero runtime dependencies.
+#
+# @example Validate a single type
+#   validates :isin, sec_id: { type: :isin }
+#
+# @example Validate against an allowlist
+#   validates :ref, sec_id: { types: %i[isin cusip] }
+#
+# @example Validate against any supported type
+#   validates :ref, sec_id: true
+class SecIdValidator < ActiveModel::EachValidator
+  # Built-in English default; `%{type_name}` is interpolated by ActiveModel/I18n (template
+  # token syntax is required here, hence the cop disable).
+  DEFAULT_MESSAGE = 'is not a valid %{type_name}' # rubocop:disable Style/FormatStringToken
+
+  # Validates the validator's own options at class-load time (fail-fast on misconfiguration).
+  #
+  # @return [void]
+  # @raise [ArgumentError] if both `type:` and `types:` are given, or a named type is unknown
+  def check_validity!
+    raise ArgumentError, 'Pass either :type or :types, not both' if options[:type] && options[:types]
+    raise ArgumentError, ':types cannot be empty' if options[:types] && configured_types.empty?
+
+    configured_types&.each { |type| SecID[type] }
+  end
+
+  # Validates `value` and, with `normalize: true`, rewrites it to canonical form on success.
+  #
+  # @param record [ActiveModel::Validations] the record being validated
+  # @param attribute [Symbol] the attribute being validated
+  # @param value [Object] the attribute value
+  # @return [void]
+  def validate_each(record, attribute, value)
+    return if valid_value?(record, attribute, value)
+
+    record.errors.add(
+      attribute, :sec_id,
+      message: options[:message] || detail_reason(value) || DEFAULT_MESSAGE,
+      type_name: human_type_name
+    )
+  end
+
+  private
+
+  # Strict by default; with `normalize: true`, separator-lenient with canonical write-back on success.
+  #
+  # @param record [ActiveModel::Validations] the record being validated
+  # @param attribute [Symbol] the attribute being validated
+  # @param value [Object] the attribute value
+  # @return [Boolean] whether the value is valid (and, in normalize mode, was rewritten)
+  def valid_value?(record, attribute, value)
+    return SecID.valid?(value, types: configured_types) unless options[:normalize]
+
+    canonical = candidate_types.lazy.filter_map { |type| normalize_via(type, value) }.first
+    return false unless canonical
+
+    record.public_send("#{attribute}=", canonical)
+    true
+  end
+
+  # @param type [Symbol] the identifier type to try
+  # @param value [Object] the attribute value
+  # @return [String, nil] the canonical form of `value` as `type`, or nil if it is not valid as `type`
+  def normalize_via(type, value)
+    SecID[type].normalize(value)
+  rescue SecID::Error
+    nil
+  end
+
+  # Concrete list of candidate types for the lenient path (never nil, unlike {#configured_types}).
+  #
+  # @return [Array<Symbol>]
+  def candidate_types
+    configured_types || SecID.identifiers.map { |klass| klass.short_name.downcase.to_sym }
+  end
+
+  # sec_id's specific failure reason, only when `details: true` and a single `type:` is set;
+  # nil otherwise (allowlist/agnostic has no single type to attribute a reason to — R12).
+  #
+  # @param value [Object] the attribute value
+  # @return [String, nil]
+  def detail_reason(value)
+    return unless options[:details] && options[:type]
+
+    type = options[:type].to_sym
+    return capture_reason(type, value) if options[:normalize]
+
+    SecID[type].validate(value).errors.messages.first
+  end
+
+  # @param type [Symbol] the single configured identifier type
+  # @param value [Object] the attribute value
+  # @return [String, nil] the message of the SecID::Error raised when normalizing `value` as `type`
+  def capture_reason(type, value)
+    SecID[type].normalize(value)
+    # :nocov: unreachable — only called after normalize already raised in valid_value?, kept as a safe fallback
+    nil
+    # :nocov:
+  rescue SecID::Error => e
+    e.message
+  end
+
+  # Configured types as symbols: `[type]` for a single type, the `types:` array for an allowlist,
+  # or `nil` when type-agnostic (any supported type).
+  #
+  # @return [Array<Symbol>, nil]
+  def configured_types
+    return @configured_types if defined?(@configured_types)
+
+    @configured_types =
+      if options[:type] then [options[:type].to_sym]
+      elsif options[:types] then Array(options[:types]).map(&:to_sym)
+      end
+  end
+
+  # The type's short name for single-type mode, or a generic label for allowlist/agnostic mode.
+  #
+  # @return [String]
+  def human_type_name
+    options[:type] ? SecID[options[:type].to_sym].short_name : 'securities identifier'
+  end
+end

data/lib/sec_id/base.rb

@@ -39,9 +39,9 @@ module SecID
   #     end
   #   end
   class Base
-    include IdentifierMetadata
     include Normalizable
     include Validatable
+    include Generatable
 
     # @return [String] the original input after normalization (stripped and uppercased)
     attr_reader :full_id
@@ -49,9 +49,42 @@ module SecID
     # @return [String, nil] the main identifier portion (without check digit)
     attr_reader :identifier
 
+    class << self
+      # @return [String] the unqualified class name (e.g. "ISIN", "CUSIP")
+      def short_name = @short_name ||= name.split('::').last
+
+      # @return [String] the full human-readable standard name
+      def full_name = self::FULL_NAME
+
+      # @return [Integer, Range, Array<Integer>] the fixed length, valid length range, or discrete valid lengths
+      def id_length = self::ID_LENGTH
+
+      # Valid length values, for length-table indexing. Integer wraps to a
+      # one-element Array; Range and Array both yield their own elements.
+      #
+      # @return [Array<Integer>, Range]
+      def length_values = (v = self::ID_LENGTH).is_a?(Integer) ? [v] : v
+
+      # Specificity weight from ID_LENGTH: fewer valid lengths ranks more specific.
+      #
+      # @return [Integer]
+      def length_specificity = (v = self::ID_LENGTH).is_a?(Integer) ? 1 : v.size
+
+      # @return [String] a representative valid identifier string
+      def example = self::EXAMPLE
+
+      # @return [Boolean] true if this identifier type uses a check digit
+      def has_check_digit?
+        return @has_check_digit if defined?(@has_check_digit)
+
+        @has_check_digit = ancestors.include?(SecID::Checkable)
+      end
+    end
+
     # @api private
     def self.inherited(subclass)
       super
+      # Skip anonymous classes and classes outside the SecID namespace (e.g. in tests)
       SecID.__send__(:register_identifier, subclass) if subclass.name&.start_with?('SecID::')
     end
 
@@ -89,6 +122,13 @@ module SecID
       }
     end
 
+    # Returns a JSON-compatible hash representation.
+    #
+    # @return [Hash]
+    def as_json(*)
+      to_h
+    end
+
     protected
 
     # @return [String]

data/lib/sec_id/bic/country_codes.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module SecID
+  class BIC < Base
+    # Frozen set of country codes accepted in a BIC's positions 5-6.
+    #
+    # The set is the ISO 3166-1 alpha-2 officially-assigned codes, extended with
+    # SWIFT-recognized codes that are not (yet) in ISO 3166-1 — currently `XK`
+    # (Kosovo), which SWIFT assigns BICs under.
+    #
+    # @api private
+    # @see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
+    # rubocop:disable Metrics/CollectionLiteralLength
+    COUNTRY_CODES = Set.new(
+      %w[
+        AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ
+        BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ
+        CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ
+        DE DJ DK DM DO DZ
+        EC EE EG EH ER ES ET
+        FI FJ FK FM FO FR
+        GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY
+        HK HM HN HR HT HU
+        ID IE IL IM IN IO IQ IR IS IT
+        JE JM JO JP
+        KE KG KH KI KM KN KP KR KW KY KZ
+        LA LB LC LI LK LR LS LT LU LV LY
+        MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ
+        NA NC NE NF NG NI NL NO NP NR NU NZ
+        OM
+        PA PE PF PG PH PK PL PM PN PR PS PT PW PY
+        QA
+        RE RO RS RU RW
+        SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ
+        TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ
+        UA UG UM US UY UZ
+        VA VC VE VG VI VN VU
+        WF WS
+        YE YT
+        ZA ZM ZW
+        XK
+      ]
+    ).freeze
+    # rubocop:enable Metrics/CollectionLiteralLength
+  end
+end

data/lib/sec_id/bic.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require_relative 'bic/country_codes'
+
+module SecID
+  # Business Identifier Code (BIC / SWIFT code) - an international standard for
+  # identifying financial and non-financial institutions (ISO 9362).
+  #
+  # Format: 4-letter institution code + 2-letter country code + 2-alphanumeric
+  # location code, optionally followed by a 3-alphanumeric branch code (BIC8 or BIC11).
+  #
+  # Validation confirms the structure and that the embedded country code is a real
+  # ISO 3166-1 / SWIFT-recognized country. It does *not* verify that the institution,
+  # location, or branch corresponds to a registered SWIFT participant — that requires
+  # the licensed SWIFT registry.
+  #
+  # @see https://en.wikipedia.org/wiki/ISO_9362
+  #
+  # @example Validate a BIC
+  #   SecID::BIC.valid?('DEUTDEFF')     #=> true (BIC8)
+  #   SecID::BIC.valid?('DEUTDEFF500')  #=> true (BIC11)
+  #
+  # @example Access BIC components
+  #   bic = SecID::BIC.new('DEUTDEFF500')
+  #   bic.bank_code      #=> "DEUT"
+  #   bic.country_code   #=> "DE"
+  #   bic.location_code  #=> "FF"
+  #   bic.branch_code    #=> "500"
+  class BIC < Base
+    # Human-readable name of the standard.
+    FULL_NAME = 'Business Identifier Code'
+    # Valid length(s) of a normalized identifier.
+    ID_LENGTH = [8, 11].freeze
+    # A representative valid identifier.
+    EXAMPLE = 'DEUTDEFF500'
+    # Pattern matching the identifier's permitted character set.
+    VALID_CHARS_REGEX = /\A[A-Z0-9]+\z/
+
+    # Regular expression for parsing BIC components.
+    # The optional all-or-nothing branch code makes the length exactly 8 or 11.
+    ID_REGEX = /\A
+      (?<bank_code>[A-Z]{4})
+      (?<country_code>[A-Z]{2})
+      (?<location_code>[A-Z0-9]{2})
+      (?<branch_code>[A-Z0-9]{3})?
+    \z/x
+
+    # Returns the sorted array of all recognized country codes.
+    #
+    # @return [Array<String>]
+    def self.countries
+      @countries ||= COUNTRY_CODES.to_a.sort.freeze
+    end
+
+    # @return [String, nil] the 4-letter institution (bank) code
+    attr_reader :bank_code
+
+    # @return [String, nil] the 2-letter ISO 3166-1 country code
+    attr_reader :country_code
+
+    # @return [String, nil] the 2-alphanumeric location code
+    attr_reader :location_code
+
+    # @return [String, nil] the 3-alphanumeric branch code, or nil for a BIC8
+    attr_reader :branch_code
+
+    # @param bic [String] the BIC string to parse
+    def initialize(bic)
+      bic_parts = parse(bic)
+      @bank_code = bic_parts[:bank_code]
+      @country_code = bic_parts[:country_code]
+      @location_code = bic_parts[:location_code]
+      @branch_code = bic_parts[:branch_code]
+      @identifier = "#{@bank_code}#{@country_code}#{@location_code}#{@branch_code}" if @bank_code
+    end
+
+    # Generates a random BIC: 4 letters + a recognized country + 2 alphanumerics,
+    # with a 3-alphanumeric branch present about half the time (BIC8 or BIC11).
+    #
+    # @param random [Random] source of randomness
+    # @return [String] a valid 8- or 11-character BIC
+    def self.generate_body(random)
+      bank = random_string(ALPHA, 4, random: random)
+      country = countries.sample(random: random)
+      location = random_string(ALPHANUMERIC, 2, random: random)
+      branch = random.rand(2).zero? ? '' : random_string(ALPHANUMERIC, 3, random: random)
+      "#{bank}#{country}#{location}#{branch}"
+    end
+    private_class_method :generate_body
+
+    private
+
+    # @return [Hash]
+    def components = { bank_code:, country_code:, location_code:, branch_code: }
+
+    # @return [Boolean]
+    def valid_format?
+      return false unless identifier
+
+      recognized_country?
+    end
+
+    # @return [Array<Symbol>]
+    def detect_errors
+      return [:invalid_country] if identifier && !recognized_country?
+
+      super
+    end
+
+    # @param code [Symbol]
+    # @return [String]
+    def validation_message(code)
+      return "Country code '#{country_code}' is not a recognized ISO 3166 / SWIFT country" if code == :invalid_country
+
+      super
+    end
+
+    # @return [Boolean]
+    def recognized_country?
+      COUNTRY_CODES.include?(country_code)
+    end
+  end
+end

data/lib/sec_id/cei.rb

@@ -13,9 +13,13 @@ module SecID
   class CEI < Base
     include Checkable
 
+    # Human-readable name of the standard.
     FULL_NAME = 'CUSIP Entity Identifier'
+    # Valid length(s) of a normalized identifier.
     ID_LENGTH = 10
+    # A representative valid identifier.
     EXAMPLE = 'A0BCDEFGH1'
+    # Pattern matching the identifier's permitted character set.
     VALID_CHARS_REGEX = /\A[A-Z0-9]+\z/
 
     # Regular expression for parsing CEI components.
@@ -46,18 +50,26 @@ module SecID
       @check_digit = cei_parts[:check_digit]&.to_i
     end
 
-    private
-
-    # @return [Hash]
-    def components = { prefix:, numeric:, entity_id:, check_digit: }
-
-    public
-
     # @return [Integer] the calculated check digit (0-9)
     # @raise [InvalidFormatError] if the CEI format is invalid
     def calculate_check_digit
       validate_format_for_calculation!
       mod10(luhn_sum_double_add_double(reversed_digits_single(identifier)))
     end
+
+    # Generates a random CEI body: 1 letter + 1 digit + 7 alphanumeric characters.
+    #
+    # @param random [Random] source of randomness
+    # @return [String] a 9-character CEI body without check digit
+    def self.generate_body(random)
+      "#{random_string(ALPHA, 1, random: random)}#{random_string(DIGITS, 1, random: random)}" \
+        "#{random_string(ALPHANUMERIC, 7, random: random)}"
+    end
+    private_class_method :generate_body
+
+    private
+
+    # @return [Hash]
+    def components = { prefix:, numeric:, entity_id:, check_digit: }
   end
 end

data/lib/sec_id/cfi/attribute_set.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module SecID
+  class CFI < Base
+    # The ordered collection of decoded attribute {Field}s. Enumerable over the
+    # fields; also answers each present meaning as a reader method (e.g.
+    # `#voting_right`) and via `#[]` (nil-safe). Built by {Classification}.
+    class AttributeSet
+      include Enumerable
+
+      # @param fields [Array<Field>] one per non-N/A position, in order
+      def initialize(fields)
+        @fields = fields
+        fields.each { |field| define_singleton_method(field.meaning) { field } }
+        freeze
+      end
+
+      # @yieldparam field [Field]
+      # @return [Enumerator, self]
+      def each(&block)
+        return to_enum(:each) unless block
+
+        @fields.each(&block)
+        self
+      end
+
+      # @param meaning [Symbol]
+      # @return [Field, nil]
+      def [](meaning)
+        find { |field| field.meaning == meaning }
+      end
+
+      # @return [Boolean]
+      def empty?
+        @fields.empty?
+      end
+
+      # @return [Hash{Symbol => Hash}]
+      def to_h
+        @fields.to_h { |field| [field.meaning, field.to_h] }
+      end
+
+      # @return [Hash{Symbol => Hash}]
+      def as_json(*)
+        to_h
+      end
+    end
+  end
+end

data/lib/sec_id/cfi/classification.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module SecID
+  class CFI < Base
+    # The decoded ISO 10962:2021 classification of a valid CFI, built by
+    # {CFI#decode}. A frozen value object exposing the category, group, and each
+    # attribute as {Field} objects, plus `#to_s` and `#to_h`/`#as_json`.
+    #
+    # @example Decode an equity CFI
+    #   c = SecID::CFI.new('ESVUFR').decode
+    #   c.category.name                     #=> :equity
+    #   c.category.equity?                  #=> true
+    #   c.group.label                       #=> "Common/Ordinary shares"
+    #   c.attributes.voting_right.voting?   #=> true
+    #   c.attributes.payment_status.label   #=> "Fully paid"
+    #   c.to_s                              #=> "Equities / Common/Ordinary shares: Voting, ..."
+    class Classification
+      # @return [Field] the category field
+      attr_reader :category
+
+      # @return [Field] the group field
+      attr_reader :group
+
+      # @return [AttributeSet] the decoded attribute fields
+      attr_reader :attributes
+
+      # @param category_code [String]
+      # @param group_code [String]
+      # @param letters [Array<String>] the four attribute letters (positions 3-6)
+      def initialize(category_code, group_code, letters)
+        @category = build_category(category_code)
+        @group = build_group(category_code, group_code)
+        @attributes = build_attributes(category_code, group_code, letters)
+        freeze
+      end
+
+      # Renders a human-readable classification string from the ISO labels.
+      #
+      # @return [String]
+      def to_s
+        values = attributes.map(&:label).join(', ')
+        head = "#{category.label} / #{group.label}"
+        values.empty? ? head : "#{head}: #{values}"
+      end
+
+      # @return [Hash{Symbol => Object}]
+      def to_h
+        { category: category.to_h, group: group.to_h, attributes: attributes.to_h }
+      end
+
+      # @return [Hash{Symbol => Object}]
+      def as_json(*)
+        to_h
+      end
+
+      private
+
+      # @param code [String]
+      # @return [Field]
+      def build_category(code)
+        name, label = Tables::CATEGORIES.fetch(code)
+        domain = Tables::CATEGORIES.each_value.map(&:first)
+        Field.new(code, name, label, domain)
+      end
+
+      # @param category_code [String]
+      # @param code [String]
+      # @return [Field]
+      def build_group(category_code, code)
+        group = Tables.group(category_code, code)
+        domain = Tables::GROUPS.fetch(category_code).each_value.map { |definition| definition[:symbol] }
+        Field.new(code, group[:symbol], group[:label], domain)
+      end
+
+      # @param category_code [String]
+      # @param group_code [String]
+      # @param letters [Array<String>]
+      # @return [AttributeSet]
+      def build_attributes(category_code, group_code, letters)
+        positions = Tables.group(category_code, group_code)[:attributes]
+        fields = positions.zip(letters).filter_map do |position, letter|
+          build_attribute(position, letter) if position
+        end
+        AttributeSet.new(fields)
+      end
+
+      # @param position [Array(Symbol, Hash)] a [meaning, value_map] pair
+      # @param letter [String]
+      # @return [Field]
+      def build_attribute(position, letter)
+        meaning, value_map = position
+        name, label = decode_value(value_map, letter)
+        domain = value_map.each_value.map(&:first) + [:not_applicable]
+        Field.new(letter, name, label, domain, meaning: meaning)
+      end
+
+      # @param value_map [Hash{String => Array}]
+      # @param letter [String]
+      # @return [Array(Symbol, String)] the value symbol and its ISO label
+      def decode_value(value_map, letter)
+        return [:not_applicable, 'Not applicable'] if letter == 'X'
+
+        value_map.fetch(letter)
+      end
+    end
+  end
+end

data/lib/sec_id/cfi/field.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module SecID
+  class CFI < Base
+    # A single decoded CFI position: the category, the group, or one attribute.
+    # Carries its raw CFI letter (`#code`), semantic symbol (`#name`), ISO label
+    # (`#label`), and — for attributes — the group meaning it answers
+    # (`#meaning`). Defines a `<name>?` predicate for every symbol in its domain,
+    # so `category.equity?` is answerable while an out-of-domain predicate such
+    # as `category.voting?` raises `NoMethodError`.
+    #
+    # Built by {Classification}; also usable on its own.
+    class Field
+      # @return [String] the raw CFI letter (e.g. "E", "V")
+      attr_reader :code
+
+      # @return [Symbol] the semantic symbol (e.g. :equity, :voting)
+      attr_reader :name
+
+      # @return [String] the authoritative ISO label
+      attr_reader :label
+
+      # @return [Symbol, nil] the group meaning for attribute fields, nil for category/group
+      attr_reader :meaning
+
+      # @param code [String]
+      # @param name [Symbol]
+      # @param label [String]
+      # @param domain [Array<Symbol>] the symbols this field may hold; one `<symbol>?` predicate per entry
+      # @param meaning [Symbol, nil]
+      def initialize(code, name, label, domain, meaning: nil)
+        @code = code
+        @name = name
+        @label = label
+        @meaning = meaning
+        domain.each { |symbol| define_singleton_method(:"#{symbol}?") { @name == symbol } }
+        freeze
+      end
+
+      # @return [String] the ISO label
+      def to_s
+        label
+      end
+
+      # @return [Hash{Symbol => Object}]
+      def to_h
+        { code: code, name: name, label: label }
+      end
+
+      # @return [Hash{Symbol => Object}]
+      def as_json(*)
+        to_h
+      end
+    end
+  end
+end