sec_id 5.2.0 → 6.0.0

data/lib/sec_id/cfi.rb

@@ -1,29 +1,37 @@
 # frozen_string_literal: true
 
+require_relative 'cfi/tables'
+
 module SecID
   # Classification of Financial Instruments (CFI) - a 6-character alphabetic code
-  # that classifies financial instruments per ISO 10962.
+  # that classifies financial instruments per ISO 10962:2021.
   #
   # Format: 6 uppercase letters A-Z
   # - Position 1: Category code (14 valid values)
   # - Position 2: Group code (varies by category)
-  # - Positions 3-6: Attribute codes (A-Z, with X meaning "not applicable")
+  # - Positions 3-6: Attribute codes, strictly validated per group (X = "not applicable")
   #
   # @see https://en.wikipedia.org/wiki/ISO_10962
   #
   # @example Validate a CFI code
-  #   SecID::CFI.valid?('ESXXXX')  #=> true
   #   SecID::CFI.valid?('ESVUFR')  #=> true
+  #   SecID::CFI.valid?('ESZZZZ')  #=> false (Z is not a permissible equity attribute)
   #
-  # @example Access CFI components
+  # @example Access CFI components and decode the classification
   #   cfi = SecID::CFI.new('ESVUFR')
-  #   cfi.category        #=> :equity
-  #   cfi.group           #=> :common_shares
-  #   cfi.voting?         #=> true
+  #   cfi.category                                #=> :equity
+  #   cfi.group                                   #=> :common_shares
+  #   cfi.decode.category.equity?                 #=> true
+  #   cfi.decode.attributes.voting_right.voting?  #=> true
+  #   cfi.decode.to_s                             #=> "Equities / Common/Ordinary shares: Voting, ..."
   class CFI < Base
+    # Human-readable name of the standard.
     FULL_NAME = 'Classification of Financial Instruments'
+    # Valid length(s) of a normalized identifier.
     ID_LENGTH = 6
+    # A representative valid identifier.
     EXAMPLE = 'ESVUFR'
+    # Pattern matching the identifier's permitted character set.
     VALID_CHARS_REGEX = /\A[A-Z]+\z/
 
     # Regular expression for parsing CFI components.
@@ -37,134 +45,15 @@ module SecID
         (?<attr4>[A-Z]))
     \z/x
 
-    # Category codes per ISO 10962.
-    CATEGORIES = {
-      'E' => :equity,
-      'C' => :collective_investment_vehicles,
-      'D' => :debt_instruments,
-      'R' => :entitlements,
-      'O' => :listed_options,
-      'F' => :futures,
-      'S' => :swaps,
-      'H' => :non_listed_options,
-      'I' => :spot,
-      'J' => :forwards,
-      'K' => :strategies,
-      'L' => :financing,
-      'T' => :referential_instruments,
-      'M' => :miscellaneous
-    }.freeze
-
-    # Group codes per category per ISO 10962.
-    GROUPS = {
-      'E' => { # Equity
-        'S' => :common_shares,
-        'P' => :preferred_shares,
-        'C' => :convertible_common_shares,
-        'F' => :convertible_preferred_shares,
-        'L' => :limited_partnership_units,
-        'D' => :depositary_receipts,
-        'Y' => :structured_instruments,
-        'M' => :miscellaneous
-      },
-      'C' => { # Collective Investment Vehicles
-        'I' => :standard_investment_funds,
-        'H' => :hedge_funds,
-        'B' => :real_estate_investment_trusts,
-        'E' => :exchange_traded_funds,
-        'S' => :pension_funds,
-        'F' => :funds_of_funds,
-        'P' => :private_equity_funds,
-        'M' => :miscellaneous
-      },
-      'D' => { # Debt Instruments
-        'B' => :bonds,
-        'C' => :convertible_bonds,
-        'W' => :bonds_with_warrants,
-        'T' => :medium_term_notes,
-        'Y' => :money_market_instruments,
-        'S' => :structured_instruments,
-        'E' => :mortgage_backed_securities,
-        'G' => :asset_backed_securities,
-        'A' => :municipal_bonds,
-        'N' => :municipal_notes,
-        'D' => :depositary_receipts,
-        'M' => :miscellaneous
-      },
-      'R' => { # Entitlements (Rights)
-        'A' => :allotment_rights,
-        'S' => :subscription_rights,
-        'P' => :purchase_rights,
-        'W' => :warrants,
-        'F' => :mini_future_certificates,
-        'D' => :depositary_receipts,
-        'M' => :miscellaneous
-      },
-      'O' => { # Listed Options
-        'C' => :call_options,
-        'P' => :put_options,
-        'M' => :miscellaneous
-      },
-      'F' => { # Futures
-        'F' => :financial_futures,
-        'C' => :commodities_futures,
-        'M' => :miscellaneous
-      },
-      'S' => { # Swaps
-        'R' => :rates,
-        'T' => :commodities,
-        'E' => :equity,
-        'C' => :credit,
-        'F' => :foreign_exchange,
-        'M' => :miscellaneous
-      },
-      'H' => { # Non-Listed (Complex) Options
-        'C' => :call_options,
-        'P' => :put_options,
-        'M' => :miscellaneous
-      },
-      'I' => { # Spot
-        'F' => :foreign_exchange,
-        'T' => :commodities,
-        'M' => :miscellaneous
-      },
-      'J' => { # Forwards
-        'F' => :foreign_exchange,
-        'R' => :rates,
-        'T' => :commodities,
-        'E' => :equity,
-        'C' => :credit,
-        'M' => :miscellaneous
-      },
-      'K' => { # Strategies
-        'R' => :rates,
-        'T' => :commodities,
-        'E' => :equity,
-        'C' => :credit,
-        'F' => :foreign_exchange,
-        'Y' => :mixed,
-        'M' => :miscellaneous
-      },
-      'L' => { # Financing
-        'S' => :loan_lease,
-        'R' => :repurchase_agreements,
-        'P' => :securities_lending,
-        'M' => :miscellaneous
-      },
-      'T' => { # Referential Instruments
-        'I' => :currencies,
-        'C' => :commodities,
-        'R' => :interest_rates,
-        'N' => :indices,
-        'B' => :baskets,
-        'D' => :stock_dividends,
-        'M' => :miscellaneous
-      },
-      'M' => { # Miscellaneous
-        'C' => :combined_instruments,
-        'M' => :miscellaneous
-      }
-    }.each_value(&:freeze).freeze
+    # Category codes per ISO 10962:2021, derived from {SecID::CFI::Tables}
+    # (letter => symbol).
+    CATEGORIES = DeepFreeze.call(Tables::CATEGORIES.transform_values(&:first))
+
+    # Group codes per category per ISO 10962:2021, derived from
+    # {SecID::CFI::Tables} (letter => { letter => symbol }).
+    GROUPS = DeepFreeze.call(
+      Tables::GROUPS.transform_values { |groups| groups.transform_values { |group| group[:symbol] } }
+    )
 
     # Returns the category codes hash.
     #
@@ -225,92 +114,62 @@ module SecID
       GROUPS.dig(category_code, group_code)
     end
 
-    # @return [Boolean] true if category is equity
-    def equity?
-      category_code == 'E'
-    end
-
-    # Voting rights (position 3 = V). Only meaningful for equity.
+    # Decodes this CFI into its full ISO 10962:2021 classification.
     #
-    # @return [Boolean]
-    def voting?
-      equity? && attr1 == 'V'
-    end
+    # @return [Classification, nil] the classification, or nil if this CFI is invalid
+    def decode
+      return nil unless valid?
 
-    # Non-voting (position 3 = N). Only meaningful for equity.
-    #
-    # @return [Boolean]
-    def non_voting?
-      equity? && attr1 == 'N'
+      Classification.new(category_code, group_code, attribute_letters)
     end
 
-    # Restricted voting (position 3 = R). Only meaningful for equity.
-    #
-    # @return [Boolean]
-    def restricted_voting?
-      equity? && attr1 == 'R'
-    end
-
-    # Enhanced voting (position 3 = E). Only meaningful for equity.
-    #
-    # @return [Boolean]
-    def enhanced_voting?
-      equity? && attr1 == 'E'
-    end
-
-    # Ownership restrictions exist (position 4 = T). Only meaningful for equity.
-    #
-    # @return [Boolean]
-    def restrictions?
-      equity? && attr2 == 'T'
-    end
-
-    # No ownership restrictions (position 4 = U). Only meaningful for equity.
-    #
-    # @return [Boolean]
-    def no_restrictions?
-      equity? && attr2 == 'U'
+    # @return [String]
+    def to_s
+      identifier.to_s
     end
 
-    # Fully paid shares (position 5 = F). Only meaningful for equity.
+    # Generates a random CFI: a category, a valid group, and per-position
+    # attribute letters sampled only from the letters the tables permit (each
+    # position also allows X; pure-N/A positions allow only X). The ED
+    # cross-position rule is honored so every generated code is valid.
     #
-    # @return [Boolean]
-    def fully_paid?
-      equity? && attr3 == 'F'
+    # @param random [Random] source of randomness
+    # @return [String] a 6-character CFI code
+    def self.generate_body(random)
+      category_code = Tables::CATEGORIES.keys.sample(random: random)
+      group_code = Tables::GROUPS[category_code].keys.sample(random: random)
+      attributes = Tables::GROUPS[category_code][group_code][:attributes]
+      letters = attributes.map { |position| sample_attribute(position, random) }
+      enforce_ed_rule(category_code, group_code, letters, random)
+      "#{category_code}#{group_code}#{letters.join}"
     end
+    private_class_method :generate_body
 
-    # Nil paid shares (position 5 = O). Only meaningful for equity.
-    #
-    # @return [Boolean]
-    def nil_paid?
-      equity? && attr3 == 'O'
-    end
+    # @param position [Array, nil] a [meaning, value_map] pair or nil (N/A)
+    # @param random [Random] source of randomness
+    # @return [String] a permitted letter for the position (X for N/A positions)
+    def self.sample_attribute(position, random)
+      return 'X' if position.nil?
 
-    # Partly paid shares (position 5 = P). Only meaningful for equity.
-    #
-    # @return [Boolean]
-    def partly_paid?
-      equity? && attr3 == 'P'
+      (position.last.keys + ['X']).sample(random: random)
     end
+    private_class_method :sample_attribute
 
-    # Bearer form (position 6 = B). Only meaningful for equity.
+    # Rewrites the redemption letter to a permitted value when the ED
+    # cross-position rule applies to the sampled underlying.
     #
-    # @return [Boolean]
-    def bearer?
-      equity? && attr4 == 'B'
-    end
-
-    # Registered form (position 6 = R). Only meaningful for equity.
-    #
-    # @return [Boolean]
-    def registered?
-      equity? && attr4 == 'R'
-    end
-
-    # @return [String]
-    def to_s
-      identifier.to_s
+    # @param category_code [String]
+    # @param group_code [String]
+    # @param letters [Array<String>] the four sampled attribute letters (mutated)
+    # @param random [Random] source of randomness
+    # @return [void]
+    def self.enforce_ed_rule(category_code, group_code, letters, random)
+      return unless Tables.ed_rule_applies?(category_code, group_code, letters)
+
+      rule = Tables::ED_REDEMPTION_RULE
+      letters[rule[:redemption_position]] = rule[:allowed_redemptions].sample(random: random)
     end
+    private_class_method :enforce_ed_rule
 
     private
 
@@ -319,7 +178,7 @@ module SecID
 
     # @return [Boolean]
     def valid_format?
-      super && valid_category? && valid_group?
+      super && valid_category? && valid_group? && valid_attributes?
     end
 
     # @return [Array<Symbol>]
@@ -329,6 +188,7 @@ module SecID
       errors = []
       errors << :invalid_category unless valid_category?
       errors << :invalid_group unless valid_group?
+      errors << :invalid_attribute if errors.empty? && !valid_attributes?
       errors
     end
 
@@ -340,6 +200,8 @@ module SecID
         "Category '#{category_code}' is not a valid CFI category"
       when :invalid_group
         "Group '#{group_code}' is not valid for category '#{category_code}'"
+      when :invalid_attribute
+        attribute_error_message
       else
         super
       end
@@ -354,5 +216,73 @@ module SecID
     def valid_group?
       !GROUPS.dig(category_code, group_code).nil?
     end
+
+    # @return [Boolean] true when every attribute letter is permitted for its
+    #   position and the ED cross-position rule holds
+    def valid_attributes?
+      attribute_violations.empty?
+    end
+
+    # Positions (3-6) whose letter is not permitted by the attribute matrix or
+    # the ED cross-position rule, as [position, letter] pairs.
+    #
+    # @return [Array<Array(Integer, String)>]
+    def attribute_violations
+      @attribute_violations ||= compute_attribute_violations
+    end
+
+    # @return [Array<Array(Integer, String)>]
+    def compute_attribute_violations
+      attributes = Tables.group(category_code, group_code)[:attributes]
+      violations = attribute_letters.each_with_index.filter_map do |letter, index|
+        [index + 3, letter] unless permitted_attribute?(attributes[index], letter)
+      end
+      (violations + ed_rule_violations).uniq
+    end
+
+    # @param position [Array, nil] a [meaning, value_map] pair or nil (N/A)
+    # @param letter [String]
+    # @return [Boolean]
+    def permitted_attribute?(position, letter)
+      return true if letter == 'X'
+      return false if position.nil? # pure-N/A position accepts only X
+
+      position.last.key?(letter)
+    end
+
+    # @return [Array<Array(Integer, String)>] the redemption position when the
+    #   ED cross-position rule is violated, otherwise empty
+    def ed_rule_violations
+      return [] unless ed_rule_applies?
+
+      rule = Tables::ED_REDEMPTION_RULE
+      redemption = attribute_letters[rule[:redemption_position]]
+      return [] if rule[:allowed_redemptions].include?(redemption)
+
+      [[rule[:redemption_position] + 3, redemption]]
+    end
+
+    # @return [Boolean] true when this is an ED code whose underlying triggers
+    #   the redemption restriction
+    def ed_rule_applies?
+      Tables.ed_rule_applies?(category_code, group_code, attribute_letters)
+    end
+
+    # @return [Array<String>] the four attribute letters (positions 3-6)
+    def attribute_letters
+      [attr1, attr2, attr3, attr4]
+    end
+
+    # @return [String] a message naming the offending positions/letters/group
+    def attribute_error_message
+      return 'Strategies require XXXX in positions 3-6' if category_code == 'K'
+
+      offenders = attribute_violations.map { |position, letter| "position #{position} '#{letter}'" }.join(', ')
+      "Invalid attribute(s) for group '#{category_code}#{group_code}': #{offenders}"
+    end
   end
 end
+
+require_relative 'cfi/field'
+require_relative 'cfi/attribute_set'
+require_relative 'cfi/classification'

data/lib/sec_id/cik.rb

@@ -15,9 +15,13 @@ module SecID
   # @example Normalize a CIK to 10 digits
   #   SecID::CIK.normalize('1521365')  #=> '0001521365'
   class CIK < Base
+    # Human-readable name of the standard.
     FULL_NAME = 'Central Index Key'
+    # Valid length(s) of a normalized identifier.
     ID_LENGTH = (1..10)
+    # A representative valid identifier.
     EXAMPLE = '0001521365'
+    # Pattern matching the identifier's permitted character set.
     VALID_CHARS_REGEX = /\A[0-9]+\z/
 
     # Regular expression for parsing CIK components.
@@ -54,5 +58,14 @@ module SecID
     def to_s
       full_id
     end
+
+    # Generates a random CIK: an integer rendered without leading zeros.
+    #
+    # @param random [Random] source of randomness
+    # @return [String] a 1-10 digit CIK
+    def self.generate_body(random)
+      random.rand(1..9_999_999_999).to_s
+    end
+    private_class_method :generate_body
   end
 end

data/lib/sec_id/concerns/checkable.rb

@@ -83,7 +83,7 @@ module SecID
       end
 
       # @param id [String] the identifier to calculate check digit for
-      # @return [Integer] the calculated check digit
+      # @return [Integer, String] the calculated check digit
       # @raise [InvalidFormatError] if the identifier format is invalid
       def check_digit(id)
         new(id).calculate_check_digit
@@ -117,7 +117,7 @@ module SecID
 
     # Subclasses must override this method to implement their check-digit algorithm.
     #
-    # @return [Integer] the calculated check digit
+    # @return [Integer, String] the calculated check digit
     # @raise [NotImplementedError] if subclass doesn't implement
     # @raise [InvalidFormatError] if the identifier format is invalid
     def calculate_check_digit

data/lib/sec_id/concerns/generatable.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module SecID
+  # Provides generation of new, format-valid identifiers for use as test fixtures.
+  #
+  # Including classes define a class-level `generate_body(random)` returning a valid
+  # body (the identifier without its check digit). The default {ClassMethods#generate}
+  # builds an instance from that body and restores the check digit for check-digit types.
+  # Types whose shape is not "body (+ check digit)" compose the full identifier in
+  # `generate_body` (CFI, FISN) or override `generate` entirely (OCC).
+  #
+  # @note Generated identifiers are valid in format only — they are not real,
+  #   registered securities. Country codes, prefixes, dates, and attributes are random.
+  #
+  # @example Generate a fixture
+  #   SecID::ISIN.generate           #=> #<SecID::ISIN ...> (valid?)
+  #   SecID::ISIN.generate.valid?    #=> true
+  #
+  # @example Reproducible output via a seeded Random
+  #   SecID::ISIN.generate(random: Random.new(42)) == SecID::ISIN.generate(random: Random.new(42))
+  module Generatable
+    # Uppercase letters A-Z.
+    ALPHA = ('A'..'Z').to_a.freeze
+
+    # Decimal digits 0-9.
+    DIGITS = ('0'..'9').to_a.freeze
+
+    # Alphanumeric characters (digits then uppercase letters).
+    ALPHANUMERIC = (DIGITS + ALPHA).freeze
+
+    # @api private
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class methods added when Generatable is included.
+    module ClassMethods
+      # Generates a new, format-valid identifier instance.
+      #
+      # @note Generated identifiers are valid in format only — they are not real,
+      #   registered securities.
+      #
+      # @param random [Random] seedable source for reproducible output
+      # @return [self] a generated instance of the identifier type (e.g. {SecID::ISIN}) for which `valid?` is true
+      def generate(random: Random.new)
+        instance = new(generate_body(random))
+        has_check_digit? ? instance.restore! : instance
+      end
+
+      private
+
+      # Subclasses must implement this to return a valid body (identifier without check digit),
+      # unless they override {#generate} entirely (as OCC does).
+      #
+      # @param _random [Random] source of randomness
+      # @return [String] the generated body
+      # @raise [NotImplementedError] if the identifier type does not implement it
+      def generate_body(_random)
+        raise NotImplementedError, "#{self} must implement .generate_body"
+      end
+
+      # @param charset [Array<String>] characters to draw from
+      # @param length [Integer] number of characters to generate
+      # @param random [Random] source of randomness
+      # @return [String] a random string of the given length
+      def random_string(charset, length, random:)
+        Array.new(length) { charset.sample(random: random) }.join
+      end
+    end
+  end
+end

data/lib/sec_id/concerns/normalizable.rb

@@ -5,6 +5,7 @@ module SecID
   #
   # Including classes may override `SEPARATORS` (default `/[\s-]/`) and `#normalized`.
   module Normalizable
+    # Characters stripped during normalization (whitespace and hyphens); classes may override.
     SEPARATORS = /[\s-]/
 
     # @api private

data/lib/sec_id/concerns/validatable.rb

@@ -6,13 +6,16 @@ module SecID
   # Including classes should override `#valid_format?` and optionally `#detect_errors`
   # for type-specific validation.
   module Validatable
+    # Maps error-code symbols to their exception classes; unmapped codes default to InvalidFormatError.
     ERROR_MAP = {
       invalid_check_digit: InvalidCheckDigitError,
       invalid_prefix: InvalidStructureError,
       invalid_category: InvalidStructureError,
       invalid_group: InvalidStructureError,
+      invalid_attribute: InvalidStructureError,
       invalid_bban: InvalidStructureError,
-      invalid_date: InvalidStructureError
+      invalid_date: InvalidStructureError,
+      invalid_country: InvalidStructureError
     }.freeze
 
     # @api private
@@ -115,13 +118,20 @@ module SecID
       [:invalid_format]
     end
 
+    # Checks length against ID_LENGTH's three shapes: Range (bounds), Array
+    # (discrete valid lengths), or Integer (allows an optional check digit).
+    #
     # @return [Boolean]
     def valid_length?
       return false if full_id.empty?
 
       id_length = self.class::ID_LENGTH
-      expected = id_length.is_a?(Range) ? id_length : ((id_length - check_digit_width)..id_length)
-      expected.cover?(full_id.length)
+      len = full_id.length
+      case id_length
+      when Range then id_length.cover?(len)
+      when Array then id_length.include?(len)
+      else            ((id_length - check_digit_width)..id_length).cover?(len)
+      end
     end
 
     # @return [Boolean]
@@ -140,6 +150,7 @@ module SecID
       case code
       when :invalid_length
         expected = self.class::ID_LENGTH
+        expected = expected.join(' or ') if expected.is_a?(Array)
         "Expected #{expected} characters, got #{full_id.length}"
       when :invalid_characters
         "Contains invalid characters for #{self.class.short_name}"

data/lib/sec_id/cusip.rb

@@ -17,9 +17,13 @@ module SecID
   class CUSIP < Base
     include Checkable
 
+    # Human-readable name of the standard.
     FULL_NAME = 'Committee on Uniform Securities Identification Procedures'
+    # Valid length(s) of a normalized identifier.
     ID_LENGTH = 9
+    # A representative valid identifier.
     EXAMPLE = '037833100'
+    # Pattern matching the identifier's permitted character set.
     VALID_CHARS_REGEX = /\A[A-Z0-9*@#]+\z/
 
     # Regular expression for parsing CUSIP components.
@@ -59,6 +63,15 @@ module SecID
       mod10(luhn_sum_double_add_double(reversed_digits_single(identifier)))
     end
 
+    # Generates a random CUSIP body: 8 alphanumeric characters.
+    #
+    # @param random [Random] source of randomness
+    # @return [String] an 8-character CUSIP body without check digit
+    def self.generate_body(random)
+      random_string(ALPHANUMERIC, 8, random: random)
+    end
+    private_class_method :generate_body
+
     # @param country_code [String] the ISO 3166-1 alpha-2 country code (must be CGS country)
     # @return [ISIN] a new ISIN instance
     # @raise [InvalidFormatError] if the country code is not a CGS country
@@ -70,16 +83,14 @@ module SecID
       ISIN.new(country_code + restore).restore!
     end
 
-    private
-
-    # @return [Hash]
-    def components = { cusip6:, issue:, check_digit: }
-
-    public
-
     # @return [Boolean] true if first character is a letter (CINS identifier)
     def cins?
       cusip6[0] < '0' || cusip6[0] > '9'
     end
+
+    private
+
+    # @return [Hash]
+    def components = { cusip6:, issue:, check_digit: }
   end
 end

data/lib/sec_id/deep_freeze.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module SecID
+  # Recursively freezes a nested structure of Hashes and Arrays and returns it.
+  # Used to make the CFI reference tables and their derived lookups deeply
+  # immutable in one call instead of freezing each level by hand.
+  module DeepFreeze
+    # @param object [Object] the (possibly nested) Hash/Array structure to freeze
+    # @return [Object] the same object, deeply frozen
+    def self.call(object)
+      case object
+      when Hash then object.each_value { |value| call(value) }
+      when Array then object.each { |value| call(value) }
+      end
+      object.freeze
+    end
+  end
+end