sec_id 4.4.1 → 5.1.0

data/lib/sec_id/concerns/validatable.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module SecID
+  # Provides validation methods for identifier types.
+  #
+  # Including classes should override `#valid_format?` and optionally `#detect_errors`
+  # for type-specific validation.
+  module Validatable
+    ERROR_MAP = {
+      invalid_check_digit: InvalidCheckDigitError,
+      invalid_prefix: InvalidStructureError,
+      invalid_category: InvalidStructureError,
+      invalid_group: InvalidStructureError,
+      invalid_bban: InvalidStructureError,
+      invalid_date: InvalidStructureError
+    }.freeze
+
+    # @api private
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class methods added when Validatable is included.
+    module ClassMethods
+      # @param id [String] the identifier to validate
+      # @return [Boolean]
+      def valid?(id)
+        new(id).valid?
+      end
+
+      # Validates the identifier and returns the instance (with errors cached).
+      #
+      # @param id [String] the identifier to validate
+      # @return [Base] the identifier instance
+      def validate(id)
+        new(id).validate
+      end
+
+      # Validates the identifier, raising an exception if invalid.
+      #
+      # @param id [String] the identifier to validate
+      # @return [Base] the identifier instance
+      # @raise [InvalidFormatError, InvalidCheckDigitError, InvalidStructureError]
+      def validate!(id)
+        new(id).validate!
+      end
+
+      # Maps an error code symbol to its corresponding exception class.
+      #
+      # @param code [Symbol]
+      # @return [Class]
+      def error_class_for(code)
+        ERROR_MAP.fetch(code, InvalidFormatError)
+      end
+    end
+
+    # @return [Boolean]
+    def valid?
+      valid_format?
+    end
+
+    # Eagerly triggers validation and caches errors.
+    #
+    # @return [self]
+    def validate
+      errors
+      self
+    end
+
+    # Returns an {Errors} object with error codes and human-readable messages.
+    #
+    # @return [Errors]
+    def errors
+      return @errors if defined?(@errors)
+
+      @errors = Errors.new(error_codes.map { |code| build_error(code, validation_message(code)) })
+    end
+
+    # Validates and returns self if valid, raises an exception otherwise.
+    #
+    # @return [self]
+    # @raise [InvalidFormatError, InvalidCheckDigitError, InvalidStructureError]
+    def validate!
+      return self if valid?
+
+      detail = errors.details.first
+      raise self.class.error_class_for(detail[:error]), detail[:message]
+    end
+
+    private
+
+    # Override in subclasses for additional format validation.
+    #
+    # @return [Boolean]
+    def valid_format?
+      !identifier.nil?
+    end
+
+    # Returns an array of error code symbols describing why validation failed.
+    #
+    # @return [Array<Symbol>]
+    def error_codes
+      return [] if valid_format?
+
+      detect_errors
+    end
+
+    # Three-stage fallback for format error detection: length, characters, then structure.
+    #
+    # @return [Array<Symbol>]
+    def detect_errors
+      return [:invalid_length] unless valid_length?
+      return [:invalid_characters] unless valid_characters?
+
+      [:invalid_format]
+    end
+
+    # @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)
+    end
+
+    # @return [Boolean]
+    def valid_characters?
+      full_id.match?(self.class::VALID_CHARS_REGEX)
+    end
+
+    # @return [Integer] width of the check digit (0 for non-checkable, overridden in Checkable)
+    def check_digit_width
+      0
+    end
+
+    # @param code [Symbol] error code
+    # @return [String] human-readable error message
+    def validation_message(code)
+      case code
+      when :invalid_length
+        expected = self.class::ID_LENGTH
+        "Expected #{expected} characters, got #{full_id.length}"
+      when :invalid_characters
+        "Contains invalid characters for #{self.class.short_name}"
+      when :invalid_format
+        "Does not match #{self.class.short_name} format"
+      end
+    end
+
+    # @param code [Symbol]
+    # @param message [String]
+    # @return [Hash{Symbol => Symbol, String}]
+    def build_error(code, message)
+      { error: code, message: message }.freeze
+    end
+  end
+end

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>
@@ -40,6 +45,13 @@ module SecId
       @check_digit = cusip_parts[:check_digit]&.to_i
     end
 
+    # @return [String, nil]
+    def to_pretty_s
+      return nil unless valid?
+
+      "#{cusip6} #{issue} #{check_digit}"
+    end
+
     # @return [Integer] the calculated check digit (0-9)
     # @raise [InvalidFormatError] if the CUSIP format is invalid
     def calculate_check_digit
@@ -55,12 +67,16 @@ 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
 
+    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'

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,9 +50,11 @@ module SecId
       @check_digit = figi_parts[:check_digit]&.to_i
     end
 
-    # @return [Boolean]
-    def valid_format?
-      !identifier.nil? && !RESTRICTED_PREFIXES.include?(prefix)
+    # @return [String, nil]
+    def to_pretty_s
+      return nil unless valid?
+
+      "#{prefix}G #{random_part} #{check_digit}"
     end
 
     # @return [Integer] the calculated check digit (0-9)
@@ -58,5 +63,30 @@ module SecId
       validate_format_for_calculation!
       mod10(luhn_sum_indexed(reversed_digits_single(identifier)))
     end
+
+    private
+
+    # @return [Hash]
+    def components = { prefix:, random_part:, check_digit: }
+
+    # @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
@@ -48,5 +54,10 @@ module SecId
     def to_s
       identifier.to_s
     end
+
+    private
+
+    # @return [Hash]
+    def components = { issuer:, description: }
   end
 end

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,55 @@ 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
 
+    # @return [String, nil]
+    def to_pretty_s
+      to_s.scan(/.{1,4}/).join(' ') if valid?
+    end
+
     private
 
+    # @return [Hash]
+    def components
+      hash = { country_code:, bban:, check_digit: }
+      hash[:bank_code] = bank_code if bank_code
+      hash[:branch_code] = branch_code if branch_code
+      hash[:account_number] = account_number if account_number
+      hash[:national_check] = national_check if national_check
+      hash
+    end
+
+    # @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)