sec_id 4.4.0 → 5.0.0

data/lib/sec_id/base.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-module SecId
+module SecID
   # Base class for securities identifiers that provides a common interface
-  # for validation and parsing.
+  # for validation, normalization, and parsing.
   #
   # Subclasses must implement:
   # - ID_REGEX constant with named capture groups for parsing
@@ -39,24 +39,20 @@ module SecId
   #     end
   #   end
   class Base
+    include IdentifierMetadata
+    include Normalizable
+    include Validatable
+
     # @return [String] the original input after normalization (stripped and uppercased)
-    attr_reader :full_number
+    attr_reader :full_id
 
     # @return [String, nil] the main identifier portion (without check digit)
     attr_reader :identifier
 
-    class << self
-      # @param id [String] the identifier to validate
-      # @return [Boolean]
-      def valid?(id)
-        new(id).valid?
-      end
-
-      # @param id [String] the identifier to check
-      # @return [Boolean]
-      def valid_format?(id)
-        new(id).valid_format?
-      end
+    # @api private
+    def self.inherited(subclass)
+      super
+      SecID.__send__(:register_identifier, subclass) if subclass.name&.start_with?('SecID::')
     end
 
     # Subclasses must override this method.
@@ -67,33 +63,13 @@ module SecId
       raise NotImplementedError
     end
 
-    # @return [Boolean]
-    def valid?
-      valid_format?
-    end
-
-    # Override in subclasses for additional format validation.
-    #
-    # @return [Boolean]
-    def valid_format?
-      !identifier.nil?
-    end
-
-    # @return [String]
-    def to_s
-      identifier.to_s
-    end
-    alias to_str to_s
-
     private
 
     # @param sec_id_number [String, #to_s] the identifier to parse
-    # @param upcase [Boolean] whether to upcase the input
     # @return [MatchData, Hash] the regex match data or empty hash if no match
-    def parse(sec_id_number, upcase: true)
-      @full_number = sec_id_number.to_s.strip
-      @full_number.upcase! if upcase
-      @full_number.match(self.class::ID_REGEX) || {}
+    def parse(sec_id_number)
+      @full_id = sec_id_number.to_s.strip.upcase
+      @full_id.match(self.class::ID_REGEX) || {}
     end
   end
 end

data/lib/sec_id/cei.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module SecId
+module SecID
   # CUSIP Entity Identifier (CEI) - a 10-character alphanumeric code that identifies
   # legal entities in the syndicated loan market.
   #
@@ -9,10 +9,15 @@ module SecId
   # @see https://www.cusip.com/identifiers.html
   #
   # @example Validate a CEI
-  #   SecId::CEI.valid?('A0BCDEFGH1')  #=> true
+  #   SecID::CEI.valid?('A0BCDEFGH1')  #=> true
   class CEI < Base
     include Checkable
 
+    FULL_NAME = 'CUSIP Entity Identifier'
+    ID_LENGTH = 10
+    EXAMPLE = 'A0BCDEFGH1'
+    VALID_CHARS_REGEX = /\A[A-Z0-9]+\z/
+
     # Regular expression for parsing CEI components.
     ID_REGEX = /\A
       (?<identifier>

data/lib/sec_id/cfi.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module SecId
+module SecID
   # Classification of Financial Instruments (CFI) - a 6-character alphabetic code
   # that classifies financial instruments per ISO 10962.
   #
@@ -12,15 +12,20 @@ module SecId
   # @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?('ESXXXX')  #=> true
+  #   SecID::CFI.valid?('ESVUFR')  #=> true
   #
   # @example Access CFI components
-  #   cfi = SecId::CFI.new('ESVUFR')
+  #   cfi = SecID::CFI.new('ESVUFR')
   #   cfi.category        #=> :equity
   #   cfi.group           #=> :common_shares
   #   cfi.voting?         #=> true
   class CFI < Base
+    FULL_NAME = 'Classification of Financial Instruments'
+    ID_LENGTH = 6
+    EXAMPLE = 'ESVUFR'
+    VALID_CHARS_REGEX = /\A[A-Z]+\z/
+
     # Regular expression for parsing CFI components.
     ID_REGEX = /\A
       (?<identifier>
@@ -191,13 +196,6 @@ module SecId
       @attr4 = cfi_parts[:attr4]
     end
 
-    # Validates format including category and group codes.
-    #
-    # @return [Boolean]
-    def valid_format?
-      super && valid_category? && valid_group?
-    end
-
     # Returns the semantic category name.
     #
     # @return [Symbol, nil] category symbol or nil if invalid
@@ -301,6 +299,34 @@ module SecId
 
     private
 
+    # @return [Boolean]
+    def valid_format?
+      super && valid_category? && valid_group?
+    end
+
+    # @return [Array<Symbol>]
+    def detect_errors
+      return super unless identifier
+
+      errors = []
+      errors << :invalid_category unless valid_category?
+      errors << :invalid_group unless valid_group?
+      errors
+    end
+
+    # @param code [Symbol]
+    # @return [String]
+    def validation_message(code)
+      case code
+      when :invalid_category
+        "Category '#{category_code}' is not a valid CFI category"
+      when :invalid_group
+        "Group '#{group_code}' is not valid for category '#{category_code}'"
+      else
+        super
+      end
+    end
+
     # @return [Boolean]
     def valid_category?
       CATEGORIES.key?(category_code)
@@ -308,7 +334,7 @@ module SecId
 
     # @return [Boolean]
     def valid_group?
-      GROUPS.dig(category_code, group_code) != nil
+      !GROUPS.dig(category_code, group_code).nil?
     end
   end
 end

data/lib/sec_id/cik.rb

@@ -1,22 +1,24 @@
 # frozen_string_literal: true
 
-module SecId
+module SecID
   # Central Index Key (CIK) - SEC identifier for entities filing with the SEC.
   # A 1-10 digit number that uniquely identifies entities in SEC systems.
   #
-  # @note CIK identifiers have no check digit. The {#has_check_digit?} method
-  #   returns false and validation is based solely on format.
+  # @note CIK identifiers have no check digit and validation is based solely on format.
   #
   # @see https://en.wikipedia.org/wiki/Central_Index_Key
   #
   # @example Validate a CIK
-  #   SecId::CIK.valid?('0001521365')  #=> true
-  #   SecId::CIK.valid?('1521365')     #=> true
+  #   SecID::CIK.valid?('0001521365')  #=> true
+  #   SecID::CIK.valid?('1521365')     #=> true
   #
   # @example Normalize a CIK to 10 digits
-  #   SecId::CIK.normalize!('1521365')  #=> '0001521365'
+  #   SecID::CIK.normalize('1521365')  #=> '0001521365'
   class CIK < Base
-    include Normalizable
+    FULL_NAME = 'Central Index Key'
+    ID_LENGTH = (1..10)
+    EXAMPLE = '0001521365'
+    VALID_CHARS_REGEX = /\A[0-9]+\z/
 
     # Regular expression for parsing CIK components.
     ID_REGEX = /\A
@@ -33,23 +35,24 @@ module SecId
       @identifier = cik_parts[:identifier]
     end
 
-    # Normalizes the CIK to a 10-digit zero-padded format.
-    # Updates both @full_number and @padding to reflect the normalized state.
-    #
     # @return [String] the normalized 10-digit CIK
-    # @raise [InvalidFormatError] if the CIK format is invalid
-    def normalize!
-      raise InvalidFormatError, "CIK '#{full_number}' is invalid and cannot be normalized!" unless valid_format?
+    # @raise [InvalidFormatError]
+    def normalized
+      validate!
+      @identifier.rjust(self.class::ID_LENGTH.max, '0')
+    end
 
-      @full_number = @identifier.rjust(10, '0')
-      @padding = @full_number[0, 10 - @identifier.length]
-      @full_number
+    # @return [self]
+    # @raise [InvalidFormatError]
+    def normalize!
+      super
+      @padding = @full_id[0, self.class::ID_LENGTH.max - @identifier.length]
+      self
     end
 
     # @return [String]
     def to_s
-      full_number
+      full_id
     end
-    alias to_str to_s
   end
 end

data/lib/sec_id/concerns/checkable.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module SecId
+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.
   #
@@ -10,10 +10,11 @@ module SecId
   # 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
+  # - `valid?` override that validates format and check digit
+  # - `restore` method returning full identifier string without mutation
+  # - `restore!` method to calculate and set the check digit, returning `self`
   # - `check_digit` attribute
-  # - Class-level convenience methods: `restore!`, `check_digit`
+  # - Class-level convenience methods: `restore`, `restore!`, `check_digit`
   #
   # @example Including in an identifier class
   #   class MyIdentifier < Base
@@ -63,11 +64,20 @@ module SecId
 
     # Class methods added when Checkable is included.
     module ClassMethods
-      # Restores (calculates) the check digit and returns the full identifier.
+      # Returns the full identifier string with correct check digit.
       #
       # @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
+
+      # Restores (calculates) the check digit and returns the instance.
+      #
+      # @param id_without_check_digit [String] identifier without or with incorrect check digit
+      # @return [self] the restored instance 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
@@ -84,18 +94,25 @@ module SecId
     #
     # @return [Boolean]
     def valid?
-      return false unless valid_format?
-
-      check_digit == calculate_check_digit
+      super && check_digit == calculate_check_digit
     end
 
-    # Calculates and sets the check digit, updating full_number.
+    # Returns the full identifier string with correct check digit without mutation.
     #
     # @return [String] the full identifier with correct check digit
     # @raise [InvalidFormatError] if the identifier format is invalid
+    def restore
+      "#{identifier}#{calculate_check_digit.to_s.rjust(check_digit_width, '0')}"
+    end
+
+    # Calculates and sets the check digit, updating full_id.
+    #
+    # @return [self]
+    # @raise [InvalidFormatError] if the identifier format is invalid
     def restore!
       @check_digit = calculate_check_digit
-      @full_number = to_s
+      @full_id = to_s
+      self
     end
 
     # Subclasses must override this method to implement their check-digit algorithm.
@@ -109,9 +126,10 @@ module SecId
 
     # @return [String]
     def to_s
-      "#{identifier}#{check_digit}"
+      "#{identifier}#{check_digit&.to_s&.rjust(check_digit_width, '0')}"
     end
-    alias to_str to_s
+
+    private
 
     # CUSIP/CEI style: "Double Add Double" algorithm.
     # Processes pairs of digits, doubling the first (even-positioned from right),
@@ -170,14 +188,38 @@ module SecId
       id.each_char.flat_map { |c| CHAR_TO_DIGITS.fetch(c) }.reverse!
     end
 
-    private
+    # Returns error codes including check digit validation.
+    #
+    # @return [Array<Symbol>]
+    def error_codes
+      return detect_errors unless valid_format?
+      return [:invalid_check_digit] unless check_digit == calculate_check_digit
+
+      []
+    end
+
+    # @return [Integer]
+    def check_digit_width
+      1
+    end
+
+    # @param code [Symbol]
+    # @return [String]
+    def validation_message(code)
+      if code == :invalid_check_digit
+        fmt = ->(cd) { cd.to_s.rjust(check_digit_width, '0') }
+        return "Check digit '#{fmt[check_digit]}' is invalid, expected '#{fmt[calculate_check_digit]}'"
+      end
+
+      super
+    end
 
     # @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!"
+      raise InvalidFormatError, "#{self.class.name} '#{full_id}' is invalid and check-digit cannot be calculated!"
     end
 
     # @param sum [Integer] the sum to calculate check digit from

data/lib/sec_id/concerns/identifier_metadata.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module SecID
+  # Provides class-level metadata methods for identifier types.
+  #
+  # Including classes must define constants: `FULL_NAME`, `ID_LENGTH`, `EXAMPLE`.
+  #
+  # @example
+  #   SecID::ISIN.short_name       #=> "ISIN"
+  #   SecID::ISIN.full_name        #=> "International Securities Identification Number"
+  #   SecID::ISIN.has_check_digit? #=> true
+  module IdentifierMetadata
+    # @api private
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class methods added when IdentifierMetadata is included.
+    module ClassMethods
+      # Returns the unqualified class name (e.g. "ISIN", "CUSIP").
+      #
+      # @return [String]
+      def short_name
+        @short_name ||= name.split('::').last
+      end
+
+      # Returns the full human-readable standard name.
+      #
+      # @return [String]
+      def full_name
+        self::FULL_NAME
+      end
+
+      # Returns the fixed length or valid length range for identifiers of this type.
+      #
+      # @return [Integer, Range]
+      def id_length
+        self::ID_LENGTH
+      end
+
+      # Returns a representative valid identifier string.
+      #
+      # @return [String]
+      def example
+        self::EXAMPLE
+      end
+
+      # @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
+  end
+end

data/lib/sec_id/concerns/normalizable.rb

@@ -1,20 +1,12 @@
 # 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.
+module SecID
+  # Provides normalization methods for identifier types.
   #
-  # @example
-  #   class MyIdentifier < Base
-  #     include Normalizable
-  #
-  #     def normalize!
-  #       # implementation
-  #     end
-  #   end
-  #
-  #   MyIdentifier.normalize!('ABC123')  #=> normalized string
+  # Including classes may override `SEPARATORS` (default `/[\s-]/`) and `#normalized`.
   module Normalizable
+    SEPARATORS = /[\s-]/
+
     # @api private
     def self.included(base)
       base.extend(ClassMethods)
@@ -26,10 +18,44 @@ module SecId
       #
       # @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!
+      # @raise [InvalidFormatError, InvalidCheckDigitError, InvalidStructureError]
+      def normalize(id)
+        cleaned = id.to_s.strip.gsub(self::SEPARATORS, '')
+        new(cleaned.upcase).normalized
       end
     end
+
+    # Returns the canonical normalized form of this identifier.
+    #
+    # @return [String]
+    # @raise [InvalidFormatError, InvalidCheckDigitError, InvalidStructureError]
+    def normalized
+      validate!
+      to_s
+    end
+
+    # @!method normalize
+    #   @return [String]
+    #   @raise [InvalidFormatError, InvalidCheckDigitError, InvalidStructureError]
+    alias normalize normalized
+
+    # Normalizes this identifier in place, updating {#full_id}.
+    #
+    # @return [self]
+    # @raise [InvalidFormatError, InvalidCheckDigitError, InvalidStructureError]
+    def normalize!
+      @full_id = normalized
+      self
+    end
+
+    # @return [String]
+    def to_s
+      identifier.to_s
+    end
+
+    # @return [String]
+    def to_str
+      to_s
+    end
   end
 end

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