sec_id 4.2.0 → 4.4.0

data/lib/sec_id/concerns/checkable.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module SecId
+  # Provides check-digit validation and calculation for securities identifiers.
+  # Include this module in classes that have a check digit as part of their format.
+  #
+  # Including classes must implement:
+  # - `calculate_check_digit` method that returns the calculated check digit value
+  #
+  # This module provides:
+  # - Character-to-digit mapping constants
+  # - Luhn algorithm variants for check-digit calculation
+  # - `valid?` override that validates the check digit
+  # - `restore!` method to calculate and set the check digit
+  # - `check_digit` attribute
+  # - Class-level convenience methods: `restore!`, `check_digit`
+  #
+  # @example Including in an identifier class
+  #   class MyIdentifier < Base
+  #     include Checkable
+  #
+  #     def calculate_check_digit
+  #       validate_format_for_calculation!
+  #       mod10(luhn_sum_standard(reversed_digits_multi(identifier)))
+  #     end
+  #   end
+  #
+  # @see https://en.wikipedia.org/wiki/Luhn_algorithm
+  module Checkable
+    # Character-to-digit mapping for Luhn algorithm variants.
+    # Maps alphanumeric characters to digit arrays for multi-digit expansion.
+    # Used by ISIN for check-digit calculation.
+    CHAR_TO_DIGITS = {
+      '0' => 0,      '1' => 1,      '2' => 2,      '3' => 3,      '4' => 4,
+      '5' => 5,      '6' => 6,      '7' => 7,      '8' => 8,      '9' => 9,
+      'A' => [1, 0], 'B' => [1, 1], 'C' => [1, 2], 'D' => [1, 3], 'E' => [1, 4],
+      'F' => [1, 5], 'G' => [1, 6], 'H' => [1, 7], 'I' => [1, 8], 'J' => [1, 9],
+      'K' => [2, 0], 'L' => [2, 1], 'M' => [2, 2], 'N' => [2, 3], 'O' => [2, 4],
+      'P' => [2, 5], 'Q' => [2, 6], 'R' => [2, 7], 'S' => [2, 8], 'T' => [2, 9],
+      'U' => [3, 0], 'V' => [3, 1], 'W' => [3, 2], 'X' => [3, 3], 'Y' => [3, 4], 'Z' => [3, 5],
+      '*' => [3, 6], '@' => [3, 7], '#' => [3, 8]
+    }.freeze
+
+    # Character-to-digit mapping for single-digit conversion.
+    # Maps alphanumeric characters to values 0-38 (A=10, B=11, ..., Z=35, *=36, @=37, #=38).
+    # Used by CUSIP, FIGI, SEDOL, LEI, and IBAN for check-digit calculations.
+    CHAR_TO_DIGIT = {
+      '0' => 0,  '1' => 1,  '2' => 2,  '3' => 3,  '4' =>  4,
+      '5' => 5,  '6' => 6,  '7' => 7,  '8' => 8,  '9' =>  9,
+      'A' => 10, 'B' => 11, 'C' => 12, 'D' => 13, 'E' => 14,
+      'F' => 15, 'G' => 16, 'H' => 17, 'I' => 18, 'J' => 19,
+      'K' => 20, 'L' => 21, 'M' => 22, 'N' => 23, 'O' => 24,
+      'P' => 25, 'Q' => 26, 'R' => 27, 'S' => 28, 'T' => 29,
+      'U' => 30, 'V' => 31, 'W' => 32, 'X' => 33, 'Y' => 34, 'Z' => 35,
+      '*' => 36, '@' => 37, '#' => 38
+    }.freeze
+
+    # @api private
+    def self.included(base)
+      base.attr_reader :check_digit
+      base.extend(ClassMethods)
+    end
+
+    # Class methods added when Checkable is included.
+    module ClassMethods
+      # Restores (calculates) the check digit and returns the full identifier.
+      #
+      # @param id_without_check_digit [String] identifier without or with incorrect check digit
+      # @return [String] the full identifier with correct check digit
+      # @raise [InvalidFormatError] if the identifier format is invalid
+      def restore!(id_without_check_digit)
+        new(id_without_check_digit).restore!
+      end
+
+      # @param id [String] the identifier to calculate check digit for
+      # @return [Integer] the calculated check digit
+      # @raise [InvalidFormatError] if the identifier format is invalid
+      def check_digit(id)
+        new(id).calculate_check_digit
+      end
+    end
+
+    # Validates format and check digit.
+    #
+    # @return [Boolean]
+    def valid?
+      return false unless valid_format?
+
+      check_digit == calculate_check_digit
+    end
+
+    # Calculates and sets the check digit, updating full_number.
+    #
+    # @return [String] the full identifier with correct check digit
+    # @raise [InvalidFormatError] if the identifier format is invalid
+    def restore!
+      @check_digit = calculate_check_digit
+      @full_number = to_s
+    end
+
+    # Subclasses must override this method to implement their check-digit algorithm.
+    #
+    # @return [Integer] the calculated check digit
+    # @raise [NotImplementedError] if subclass doesn't implement
+    # @raise [InvalidFormatError] if the identifier format is invalid
+    def calculate_check_digit
+      raise NotImplementedError
+    end
+
+    # @return [String]
+    def to_s
+      "#{identifier}#{check_digit}"
+    end
+    alias to_str to_s
+
+    # CUSIP/CEI style: "Double Add Double" algorithm.
+    # Processes pairs of digits, doubling the first (even-positioned from right),
+    # then summing both digit's div10mod10 values.
+    #
+    # @param digits [Array<Integer>] reversed array of digit values
+    # @return [Integer] the Luhn sum
+    def luhn_sum_double_add_double(digits)
+      digits.each_slice(2).reduce(0) do |sum, (even, odd)|
+        double_even = (even || 0) * 2
+        sum + div10mod10(double_even) + div10mod10(odd || 0)
+      end
+    end
+
+    # FIGI style: index-based doubling algorithm.
+    # Doubles odd-indexed digits (from right), then sums div10mod10 values.
+    #
+    # @param digits [Array<Integer>] reversed array of digit values
+    # @return [Integer] the Luhn sum
+    def luhn_sum_indexed(digits)
+      digits.each_with_index.reduce(0) do |sum, (digit, index)|
+        digit *= 2 if index.odd?
+        sum + div10mod10(digit)
+      end
+    end
+
+    # ISIN style: standard Luhn with subtract-9 for values > 9.
+    # Processes pairs of digits, doubling the first (even-positioned from right),
+    # subtracting 9 if result > 9.
+    #
+    # @param digits [Array<Integer>] reversed array of digit values
+    # @return [Integer] the Luhn sum
+    def luhn_sum_standard(digits)
+      digits.each_slice(2).reduce(0) do |sum, (even, odd)|
+        double_even = (even || 0) * 2
+        double_even -= 9 if double_even > 9
+        sum + double_even + (odd || 0)
+      end
+    end
+
+    # Converts identifier characters to reversed digit array using single-digit mapping.
+    # Used by CUSIP, CEI, FIGI, and SEDOL.
+    #
+    # @param id [String] the identifier string
+    # @return [Array<Integer>] reversed array of digit values
+    def reversed_digits_single(id)
+      id.each_char.map { |c| CHAR_TO_DIGIT.fetch(c) }.reverse!
+    end
+
+    # Converts identifier characters to reversed digit array using multi-digit mapping.
+    # Used by ISIN where letters expand to two digits.
+    #
+    # @param id [String] the identifier string
+    # @return [Array<Integer>] reversed array of digit values
+    def reversed_digits_multi(id)
+      id.each_char.flat_map { |c| CHAR_TO_DIGITS.fetch(c) }.reverse!
+    end
+
+    private
+
+    # @raise [InvalidFormatError] if valid_format? returns false
+    # @return [void]
+    def validate_format_for_calculation!
+      return if valid_format?
+
+      raise InvalidFormatError, "#{self.class.name} '#{full_number}' is invalid and check-digit cannot be calculated!"
+    end
+
+    # @param sum [Integer] the sum to calculate check digit from
+    # @return [Integer] check digit (0-9)
+    def mod10(sum)
+      (10 - (sum % 10)) % 10
+    end
+
+    # @param number [Integer] number to split
+    # @return [Integer] sum of tens and units digits
+    def div10mod10(number)
+      (number / 10) + (number % 10)
+    end
+
+    # @param numeric_string [String] numeric string representation
+    # @return [Integer] check digit value (1-98)
+    def mod97(numeric_string)
+      98 - (numeric_string.to_i % 97)
+    end
+  end
+end

data/lib/sec_id/concerns/normalizable.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SecId
+  # Provides normalize! class method delegation for identifiers that support normalization.
+  # Include this module in classes that implement an instance-level normalize! method.
+  #
+  # @example
+  #   class MyIdentifier < Base
+  #     include Normalizable
+  #
+  #     def normalize!
+  #       # implementation
+  #     end
+  #   end
+  #
+  #   MyIdentifier.normalize!('ABC123')  #=> normalized string
+  module Normalizable
+    # @api private
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class methods added when Normalizable is included.
+    module ClassMethods
+      # Normalizes the identifier to its canonical format.
+      #
+      # @param id [String, #to_s] the identifier to normalize
+      # @return [String] the normalized identifier
+      # @raise [InvalidFormatError] if the identifier format is invalid
+      def normalize!(id)
+        new(id).normalize!
+      end
+    end
+  end
+end

data/lib/sec_id/cusip.rb

@@ -1,8 +1,23 @@
 # frozen_string_literal: true
 
 module SecId
-  # https://en.wikipedia.org/wiki/CUSIP
+  # Committee on Uniform Securities Identification Procedures (CUSIP) - a 9-character
+  # alphanumeric code that identifies North American securities.
+  #
+  # Format: 6-character issuer code (CUSIP-6) + 2-character issue number + 1-digit check digit
+  #
+  # @see https://en.wikipedia.org/wiki/CUSIP
+  #
+  # @example Validate a CUSIP
+  #   SecId::CUSIP.valid?('037833100')  #=> true
+  #
+  # @example Convert to ISIN
+  #   cusip = SecId::CUSIP.new('037833100')
+  #   cusip.to_isin('US')  #=> #<SecId::ISIN>
   class CUSIP < Base
+    include Checkable
+
+    # Regular expression for parsing CUSIP components.
     ID_REGEX = /\A
       (?<identifier>
         (?<cusip6>[A-Z0-9]{5}[A-Z0-9*@#])
@@ -10,8 +25,13 @@ module SecId
       (?<check_digit>\d)?
     \z/x
 
-    attr_reader :cusip6, :issue
+    # @return [String, nil] the 6-character issuer code
+    attr_reader :cusip6
+
+    # @return [String, nil] the 2-character issue number
+    attr_reader :issue
 
+    # @param cusip [String] the CUSIP string to parse
     def initialize(cusip)
       cusip_parts = parse cusip
       @identifier = cusip_parts[:identifier]
@@ -20,14 +40,16 @@ module SecId
       @check_digit = cusip_parts[:check_digit]&.to_i
     end
 
+    # @return [Integer] the calculated check digit (0-9)
+    # @raise [InvalidFormatError] if the CUSIP format is invalid
     def calculate_check_digit
-      unless valid_format?
-        raise InvalidFormatError, "CUSIP '#{full_number}' is invalid and check-digit cannot be calculated!"
-      end
-
-      mod10(modified_luhn_sum)
+      validate_format_for_calculation!
+      mod10(luhn_sum_double_add_double(reversed_digits_single(identifier)))
     end
 
+    # @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
     def to_isin(country_code)
       unless ISIN::CGS_COUNTRY_CODES.include?(country_code)
         raise(InvalidFormatError, "'#{country_code}' is not a CGS country code!")
@@ -39,23 +61,9 @@ module SecId
       isin
     end
 
-    # CUSIP International Numbering System
+    # @return [Boolean] true if first character is a letter (CINS identifier)
     def cins?
       cusip6[0] < '0' || cusip6[0] > '9'
     end
-
-    private
-
-    # https://en.wikipedia.org/wiki/Luhn_algorithm
-    def modified_luhn_sum
-      reversed_id_digits.each_slice(2).reduce(0) do |sum, (even, odd)|
-        double_even = (even || 0) * 2
-        sum + div10mod10(double_even) + div10mod10(odd || 0)
-      end
-    end
-
-    def reversed_id_digits
-      identifier.each_char.map(&method(:char_to_digit)).reverse!
-    end
   end
 end

data/lib/sec_id/figi.rb

@@ -3,7 +3,24 @@
 require 'set'
 
 module SecId
+  # Financial Instrument Global Identifier (FIGI) - a 12-character alphanumeric code
+  # that uniquely identifies financial instruments.
+  #
+  # Format: 2-character prefix + 'G' + 8-character random part + 1-digit check digit
+  # Note: FIGI excludes vowels (A, E, I, O, U) from valid characters.
+  #
+  # @see https://en.wikipedia.org/wiki/Financial_Instrument_Global_Identifier
+  #
+  # @example Validate a FIGI
+  #   SecId::FIGI.valid?('BBG000BLNQ16')  #=> true
+  #
+  # @example Restore check digit
+  #   SecId::FIGI.restore!('BBG000BLNQ1')  #=> 'BBG000BLNQ16'
   class FIGI < Base
+    include Checkable
+
+    # Regular expression for parsing FIGI components.
+    # The third character must be 'G'. Excludes vowels from valid characters.
     ID_REGEX = /\A
       (?<identifier>
         (?<prefix>[B-DF-HJ-NP-TV-Z0-9]{2})
@@ -12,10 +29,16 @@ module SecId
       (?<check_digit>\d)?
     \z/x
 
+    # Country-code prefixes that are restricted from use in FIGI.
     RESTRICTED_PREFIXES = Set.new %w[BS BM GG GB GH KY VG]
 
-    attr_reader :prefix, :random_part
+    # @return [String, nil] the 2-character prefix
+    attr_reader :prefix
+
+    # @return [String, nil] the 8-character random part
+    attr_reader :random_part
 
+    # @param figi [String] the FIGI string to parse
     def initialize(figi)
       figi_parts = parse figi
       @identifier = figi_parts[:identifier]
@@ -24,30 +47,16 @@ module SecId
       @check_digit = figi_parts[:check_digit]&.to_i
     end
 
+    # @return [Boolean]
     def valid_format?
       !identifier.nil? && !RESTRICTED_PREFIXES.include?(prefix)
     end
 
+    # @return [Integer] the calculated check digit (0-9)
+    # @raise [InvalidFormatError] if the FIGI format is invalid
     def calculate_check_digit
-      unless valid_format?
-        raise InvalidFormatError, "FIGI '#{full_number}' is invalid and check-digit cannot be calculated!"
-      end
-
-      mod10(modified_luhn_sum)
-    end
-
-    private
-
-    # https://en.wikipedia.org/wiki/Luhn_algorithm
-    def modified_luhn_sum
-      reversed_id_digits.each_with_index.reduce(0) do |sum, (digit, index)|
-        digit *= 2 if index.odd?
-        sum + digit.divmod(10).sum
-      end
-    end
-
-    def reversed_id_digits
-      identifier.each_char.map(&method(:char_to_digit)).reverse!
+      validate_format_for_calculation!
+      mod10(luhn_sum_indexed(reversed_digits_single(identifier)))
     end
   end
 end

data/lib/sec_id/fisn.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module SecId
+  # Financial Instrument Short Name (FISN) - a human-readable short name for financial
+  # instruments per ISO 18774.
+  #
+  # Format: Issuer Name/Abbreviated Instrument Description
+  # - Total length: 1-35 characters
+  # - Issuer: 1-15 characters (uppercase A-Z, digits 0-9, space)
+  # - Separator: forward slash (/)
+  # - Description: 1-19 characters (uppercase A-Z, digits 0-9, space)
+  #
+  # @see https://en.wikipedia.org/wiki/ISO_18774
+  #
+  # @example Validate a FISN
+  #   SecId::FISN.valid?('APPLE INC/SH')  #=> true
+  #   SecId::FISN.valid?('apple inc/sh')  #=> true (normalized to uppercase)
+  #
+  # @example Access FISN components
+  #   fisn = SecId::FISN.new('APPLE INC/SH')
+  #   fisn.issuer       #=> 'APPLE INC'
+  #   fisn.description  #=> 'SH'
+  class FISN < Base
+    # Regular expression for parsing FISN components.
+    # Issuer: 1-15 chars, Description: 1-19 chars, Total: max 35 chars
+    ID_REGEX = %r{\A
+      (?<identifier>
+        (?<issuer>[A-Z0-9 ]{1,15})
+        /
+        (?<description>[A-Z0-9 ]{1,19}))
+    \z}x
+
+    # @return [String, nil] the issuer name portion (before the slash)
+    attr_reader :issuer
+
+    # @return [String, nil] the abbreviated instrument description (after the slash)
+    attr_reader :description
+
+    # @param fisn [String] the FISN string to parse
+    def initialize(fisn)
+      fisn_parts = parse(fisn)
+      @identifier = fisn_parts[:identifier]
+      @issuer = fisn_parts[:issuer]
+      @description = fisn_parts[:description]
+    end
+
+    # @return [String]
+    def to_s
+      identifier.to_s
+    end
+  end
+end