sec_id 4.4.1 → 5.0.0

data/lib/sec_id/cusip.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module SecId
+module SecID
   # Committee on Uniform Securities Identification Procedures (CUSIP) - a 9-character
   # alphanumeric code that identifies North American securities.
   #
@@ -9,14 +9,19 @@ module SecId
   # @see https://en.wikipedia.org/wiki/CUSIP
   #
   # @example Validate a CUSIP
-  #   SecId::CUSIP.valid?('037833100')  #=> true
+  #   SecID::CUSIP.valid?('037833100')  #=> true
   #
   # @example Convert to ISIN
-  #   cusip = SecId::CUSIP.new('037833100')
-  #   cusip.to_isin('US')  #=> #<SecId::ISIN>
+  #   cusip = SecID::CUSIP.new('037833100')
+  #   cusip.to_isin('US')  #=> #<SecID::ISIN>
   class CUSIP < Base
     include Checkable
 
+    FULL_NAME = 'Committee on Uniform Securities Identification Procedures'
+    ID_LENGTH = 9
+    EXAMPLE = '037833100'
+    VALID_CHARS_REGEX = /\A[A-Z0-9*@#]+\z/
+
     # Regular expression for parsing CUSIP components.
     ID_REGEX = /\A
       (?<identifier>
@@ -55,10 +60,7 @@ module SecId
         raise(InvalidFormatError, "'#{country_code}' is not a CGS country code!")
       end
 
-      cusip_with_check_digit = "#{identifier}#{check_digit || calculate_check_digit}"
-      isin = ISIN.new(country_code + cusip_with_check_digit)
-      isin.restore!
-      isin
+      ISIN.new(country_code + restore).restore!
     end
 
     # @return [Boolean] true if first character is a letter (CINS identifier)

data/lib/sec_id/detector.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module SecID
+  # Detects which identifier types match a given string using a three-stage
+  # pipeline that eliminates most candidates before calling `valid?`.
+  #
+  # Stage 1 — Special-character dispatch (O(1)):
+  #   Strings containing `/`, ` `, or `*@#` route to the only types accepting those chars.
+  #
+  # Stage 2 — Length lookup (O(1) hash access):
+  #   Pre-computed table maps each possible length to candidate classes.
+  #
+  # Stage 3 — Charset pre-filter:
+  #   Survivors are filtered by their VALID_CHARS_REGEX before calling `valid?`.
+  #
+  # Typical result: 1-2 `valid?` calls instead of 13.
+  #
+  # @api private
+  class Detector
+    # @param identifier_list [Array<Class>] registered identifier classes
+    def initialize(identifier_list)
+      @classes = identifier_list.dup.freeze
+      precompute
+    end
+
+    # Detects all matching identifier types for the given string.
+    #
+    # @param str [String, nil] the identifier string to detect
+    # @return [Array<Symbol>] matching type symbols sorted by specificity
+    def call(str)
+      input = str.to_s.strip
+      return [] if input.empty?
+
+      upcased = input.upcase
+      candidates = filter_candidates(upcased)
+      validate_and_sort(input, candidates)
+    end
+
+    private
+
+    # Runs stages 1-3 to narrow candidate classes.
+    #
+    # @param upcased [String]
+    # @return [Array<Class>]
+    def filter_candidates(upcased)
+      candidates = stage1_special_chars(upcased) || stage2_length(upcased.length)
+      return candidates if candidates.empty?
+
+      stage3_charset(upcased, candidates)
+    end
+
+    # Validates candidates and returns sorted symbol keys.
+    #
+    # @param input [String]
+    # @param candidates [Array<Class>]
+    # @return [Array<Symbol>]
+    def validate_and_sort(input, candidates)
+      matches = candidates.select { |klass| klass.valid?(input) }
+      matches.sort_by! { |klass| @priority_for[klass] }
+      matches.map! { |klass| @key_for[klass] }
+    end
+
+    # @return [void]
+    def precompute
+      build_discriminator_sets
+      build_length_table
+      build_priority_table
+      build_key_table
+    end
+
+    # Classifies types by which special characters their VALID_CHARS_REGEX accepts.
+    #
+    # @return [void]
+    def build_discriminator_sets
+      @slash_types = @classes.select { |k| accepts_char?(k, '/') }
+      space_types = @classes.select { |k| accepts_char?(k, ' ') }
+      @space_only_types = space_types - @slash_types
+      @special_types = @classes.select { |k| accepts_char?(k, '*') }
+    end
+
+    # Builds a Hash mapping each possible length to the classes that accept it.
+    #
+    # @return [void]
+    def build_length_table
+      @candidates_by_length = Hash.new { |h, k| h[k] = [] }
+      @classes.each do |klass|
+        id_length = klass::ID_LENGTH
+        lengths = id_length.is_a?(Range) ? id_length : [id_length]
+        lengths.each { |len| @candidates_by_length[len] << klass }
+      end
+      @candidates_by_length.each_value(&:freeze)
+    end
+
+    # Builds composite sort keys: check-digit types first, then smaller range, then load order.
+    #
+    # @return [void]
+    def build_priority_table
+      @priority_for = {}
+      @classes.each_with_index do |klass, index|
+        check_digit_rank = klass.has_check_digit? ? 0 : 1
+        id_length = klass::ID_LENGTH
+        range_size = id_length.is_a?(Range) ? id_length.size : 1
+        @priority_for[klass] = [check_digit_rank, range_size, index].freeze
+      end
+      @priority_for.freeze
+    end
+
+    # Maps each class to its registry symbol key.
+    #
+    # @return [void]
+    def build_key_table
+      @key_for = {}
+      @classes.each { |klass| @key_for[klass] = klass.short_name.downcase.to_sym }
+      @key_for.freeze
+    end
+
+    # Stage 1: route strings with special characters to the only types that accept them.
+    # Returns nil if no special chars found (fall through to stage 2).
+    #
+    # @param upcased [String]
+    # @return [Array<Class>, nil]
+    def stage1_special_chars(upcased)
+      return @slash_types if upcased.include?('/')
+      return @space_only_types if upcased.include?(' ')
+      return @special_types if upcased.match?(/[*@#]/)
+
+      nil
+    end
+
+    # Stage 2: look up candidates by string length.
+    #
+    # @param length [Integer]
+    # @return [Array<Class>]
+    def stage2_length(length)
+      @candidates_by_length[length] || []
+    end
+
+    # Stage 3: filter candidates by character set.
+    #
+    # @param upcased [String]
+    # @param candidates [Array<Class>]
+    # @return [Array<Class>]
+    def stage3_charset(upcased, candidates)
+      candidates.select { |klass| upcased.match?(klass::VALID_CHARS_REGEX) }
+    end
+
+    # Tests whether a class's VALID_CHARS_REGEX accepts a given character.
+    #
+    # @param klass [Class]
+    # @param char [String] single character
+    # @return [Boolean]
+    def accepts_char?(klass, char)
+      char.match?(klass::VALID_CHARS_REGEX)
+    end
+  end
+end

data/lib/sec_id/errors.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module SecID
+  # Immutable value object representing validation errors for an identifier.
+  # Follows Rails/ActiveModel conventions: use {#details} for structured error data
+  # and {#messages} for human-readable strings.
+  #
+  # @example No errors
+  #   errors = SecID::Errors.new([])
+  #   errors.none?     #=> true
+  #   errors.empty?    #=> true
+  #   errors.messages  #=> []
+  #
+  # @example With errors
+  #   err = [{ error: :invalid_length, message: "Expected 12 characters, got 5" }]
+  #   errors = SecID::Errors.new(err)
+  #   errors.none?     #=> false
+  #   errors.details   #=> [{ error: :invalid_length, message: "..." }]
+  #   errors.messages  #=> ["Expected 12 characters, got 5"]
+  class Errors
+    # @return [Array<Hash{Symbol => Symbol, String}>] array of error hashes with :error and :message keys
+    attr_reader :details
+
+    # @param errors [Array<Hash{Symbol => Symbol, String}>] array of error hashes
+    def initialize(errors)
+      @details = errors.freeze
+      freeze
+    end
+
+    # @return [Array<String>] human-readable error messages
+    def messages
+      @details.map { |e| e[:message] }
+    end
+
+    # @return [Boolean] true when there are errors
+    def any?
+      !@details.empty?
+    end
+
+    # @return [Boolean] true when there are no errors
+    def empty?
+      @details.empty?
+    end
+
+    # @!method none?
+    #   @return [Boolean] true when there are no errors
+    alias none? empty?
+
+    # @return [Integer] number of errors
+    def size
+      @details.size
+    end
+
+    # Yields each error detail hash to the block.
+    #
+    # @yieldparam detail [Hash{Symbol => Symbol, String}]
+    # @return [Enumerator, self]
+    def each(&)
+      @details.each(&)
+    end
+
+    # @return [Array<String>] alias for {#messages}
+    def to_a
+      messages
+    end
+  end
+end

data/lib/sec_id/figi.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
-require 'set'
-
-module SecId
+module SecID
   # Financial Instrument Global Identifier (FIGI) - a 12-character alphanumeric code
   # that uniquely identifies financial instruments.
   #
@@ -12,13 +10,18 @@ module SecId
   # @see https://en.wikipedia.org/wiki/Financial_Instrument_Global_Identifier
   #
   # @example Validate a FIGI
-  #   SecId::FIGI.valid?('BBG000BLNQ16')  #=> true
+  #   SecID::FIGI.valid?('BBG000BLNQ16')  #=> true
   #
   # @example Restore check digit
-  #   SecId::FIGI.restore!('BBG000BLNQ1')  #=> 'BBG000BLNQ16'
+  #   SecID::FIGI.restore!('BBG000BLNQ1')  #=> #<SecID::FIGI>
   class FIGI < Base
     include Checkable
 
+    FULL_NAME = 'Financial Instrument Global Identifier'
+    ID_LENGTH = 12
+    EXAMPLE = 'BBG000BLNNH6'
+    VALID_CHARS_REGEX = /\A[B-DF-HJ-NP-TV-Z0-9]+\z/
+
     # Regular expression for parsing FIGI components.
     # The third character must be 'G'. Excludes vowels from valid characters.
     ID_REGEX = /\A
@@ -47,16 +50,33 @@ 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
       validate_format_for_calculation!
       mod10(luhn_sum_indexed(reversed_digits_single(identifier)))
     end
+
+    private
+
+    # @return [Boolean]
+    def valid_format?
+      !identifier.nil? && !RESTRICTED_PREFIXES.include?(prefix)
+    end
+
+    # @return [Array<Symbol>]
+    def detect_errors
+      return [:invalid_prefix] if identifier && RESTRICTED_PREFIXES.include?(prefix)
+
+      super
+    end
+
+    # @param code [Symbol]
+    # @return [String]
+    def validation_message(code)
+      return "Prefix '#{prefix}' is restricted" if code == :invalid_prefix
+
+      super
+    end
   end
 end

data/lib/sec_id/fisn.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module SecId
+module SecID
   # Financial Instrument Short Name (FISN) - a human-readable short name for financial
   # instruments per ISO 18774.
   #
@@ -13,14 +13,20 @@ module SecId
   # @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)
+  #   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 = SecID::FISN.new('APPLE INC/SH')
   #   fisn.issuer       #=> 'APPLE INC'
   #   fisn.description  #=> 'SH'
   class FISN < Base
+    FULL_NAME = 'Financial Instrument Short Name'
+    ID_LENGTH = (3..35)
+    EXAMPLE = 'APPLE INC/SH'
+    VALID_CHARS_REGEX = %r{\A[A-Z0-9 /]+\z}
+    SEPARATORS = /-/
+
     # Regular expression for parsing FISN components.
     # Issuer: 1-15 chars, Description: 1-19 chars, Total: max 35 chars
     ID_REGEX = %r{\A

data/lib/sec_id/iban/country_rules.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
-module SecId
-  # Country-specific BBAN validation rules for IBAN
+module SecID
+  # Country-specific BBAN validation rules for IBAN.
+  #
+  # @api private
   # rubocop:disable Metrics/ModuleLength
   module IBANCountryRules
     # Country-specific BBAN rules for EU/EEA countries

data/lib/sec_id/iban.rb

@@ -2,25 +2,30 @@
 
 require_relative 'iban/country_rules'
 
-module SecId
+module SecID
   # International Bank Account Number (IBAN) - an international standard for identifying
   # bank accounts across national borders (ISO 13616).
   #
   # Format: 2-letter country code + 2-digit check digits + BBAN (Basic Bank Account Number, 11-30 chars)
-  # Note: Unlike other SecId identifiers, the check digits are in positions 3-4, not at the end.
+  # Note: Unlike other SecID identifiers, the check digits are in positions 3-4, not at the end.
   #
   # @see https://en.wikipedia.org/wiki/International_Bank_Account_Number
   # @see https://www.iban.com/structure
   #
   # @example Validate an IBAN
-  #   SecId::IBAN.valid?('DE89370400440532013000')  #=> true
+  #   SecID::IBAN.valid?('DE89370400440532013000')  #=> true
   #
   # @example Restore check digits
-  #   SecId::IBAN.restore!('DE00370400440532013000')  #=> 'DE89370400440532013000'
+  #   SecID::IBAN.restore!('DE00370400440532013000')  #=> #<SecID::IBAN>
   class IBAN < Base
     include Checkable
     include IBANCountryRules
 
+    FULL_NAME = 'International Bank Account Number'
+    ID_LENGTH = (15..34)
+    EXAMPLE = 'GB29NWBK60161331926819'
+    VALID_CHARS_REGEX = /\A[A-Z0-9]+\z/
+
     # Regular expression for parsing IBAN components.
     # Note: Check digit positioning is handled in initialize, not in the regex.
     ID_REGEX = /\A
@@ -60,6 +65,13 @@ module SecId
       extract_bban_components if valid_format?
     end
 
+    # @return [String]
+    # @raise [InvalidFormatError] if the IBAN format is invalid
+    def restore
+      cd = calculate_check_digit
+      "#{country_code}#{cd.to_s.rjust(2, '0')}#{bban}"
+    end
+
     # @return [Integer] the calculated 2-digit check value (1-98)
     # @raise [InvalidFormatError] if the IBAN format is invalid
     def calculate_check_digit
@@ -67,13 +79,6 @@ module SecId
       mod97(numeric_string_for_check)
     end
 
-    # @return [Boolean]
-    def valid_format?
-      return false unless identifier
-
-      valid_bban_format?
-    end
-
     # @return [Boolean]
     def valid_bban_format?
       return false unless bban
@@ -96,13 +101,40 @@ module SecId
 
     # @return [String]
     def to_s
-      return full_number unless check_digit
+      return full_id unless check_digit
 
       "#{country_code}#{check_digit.to_s.rjust(2, '0')}#{bban}"
     end
 
     private
 
+    # @return [Integer]
+    def check_digit_width
+      2
+    end
+
+    # @return [Boolean]
+    def valid_format?
+      return false unless identifier
+
+      valid_bban_format?
+    end
+
+    # @return [Array<Symbol>]
+    def detect_errors
+      return [:invalid_bban] if identifier && !valid_bban_format?
+
+      super
+    end
+
+    # @param code [Symbol]
+    # @return [String]
+    def validation_message(code)
+      return "BBAN format is invalid for country '#{country_code}'" if code == :invalid_bban
+
+      super
+    end
+
     # @param rest [String] the IBAN string after country code
     # @return [void]
     def extract_check_digit_and_bban(rest)

data/lib/sec_id/isin.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module SecId
+module SecID
   # International Securities Identification Number (ISIN) - a 12-character alphanumeric code
   # that uniquely identifies a security globally.
   #
@@ -9,13 +9,18 @@ module SecId
   # @see https://en.wikipedia.org/wiki/International_Securities_Identification_Number
   #
   # @example Validate an ISIN
-  #   SecId::ISIN.valid?('US5949181045')  #=> true
+  #   SecID::ISIN.valid?('US5949181045')  #=> true
   #
   # @example Restore check digit
-  #   SecId::ISIN.restore!('US594918104')  #=> 'US5949181045'
+  #   SecID::ISIN.restore!('US594918104')  #=> #<SecID::ISIN>
   class ISIN < Base
     include Checkable
 
+    FULL_NAME = 'International Securities Identification Number'
+    ID_LENGTH = 12
+    EXAMPLE = 'US5949181045'
+    VALID_CHARS_REGEX = /\A[A-Z0-9]+\z/
+
     # Regular expression for parsing ISIN components.
     ID_REGEX = /\A
       (?<identifier>
@@ -148,9 +153,9 @@ module SecId
 
       case nsin_type
       when :cusip   then to_cusip
-      when :sedol   then SEDOL.new(nsin[2..])
-      when :wkn     then WKN.new(nsin[3..])
-      when :valoren then Valoren.new(nsin)
+      when :sedol   then to_sedol
+      when :wkn     then to_wkn
+      when :valoren then to_valoren
       else nsin # :generic - return raw string
       end
     end

data/lib/sec_id/lei.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module SecId
+module SecID
   # Legal Entity Identifier (LEI) - a 20-character alphanumeric code that
   # uniquely identifies legal entities participating in financial transactions.
   #
@@ -10,13 +10,18 @@ module SecId
   # @see https://www.gleif.org/en/about-lei/iso-17442-the-lei-code-structure
   #
   # @example Validate a LEI
-  #   SecId::LEI.valid?('529900T8BM49AURSDO55')  #=> true
+  #   SecID::LEI.valid?('529900T8BM49AURSDO55')  #=> true
   #
   # @example Calculate check digit
-  #   SecId::LEI.check_digit('529900T8BM49AURSDO')  #=> 55
+  #   SecID::LEI.check_digit('529900T8BM49AURSDO')  #=> 55
   class LEI < Base
     include Checkable
 
+    FULL_NAME = 'Legal Entity Identifier'
+    ID_LENGTH = 20
+    EXAMPLE = '7LTWFZYICNSX8D621K86'
+    VALID_CHARS_REGEX = /\A[0-9A-Z]+\z/
+
     # Regular expression for parsing LEI components.
     ID_REGEX = /\A
       (?<identifier>
@@ -52,15 +57,13 @@ module SecId
       mod97("#{numeric_identifier}00")
     end
 
-    # @return [String]
-    def to_s
-      return full_number unless check_digit
+    private
 
-      "#{identifier}#{check_digit.to_s.rjust(2, '0')}"
+    # @return [Integer]
+    def check_digit_width
+      2
     end
 
-    private
-
     # @return [String] the numeric string representation
     def numeric_identifier
       identifier.each_char.map { |char| CHAR_TO_DIGIT.fetch(char) }.join