sec_id 5.1.0 → 6.0.0

data/lib/sec_id/sedol.rb

@@ -17,9 +17,13 @@ module SecID
   class SEDOL < Base
     include Checkable
 
+    # Human-readable name of the standard.
     FULL_NAME = 'Stock Exchange Daily Official List'
+    # Valid length(s) of a normalized identifier.
     ID_LENGTH = 7
+    # A representative valid identifier.
     EXAMPLE = 'B0YBKJ7'
+    # Pattern matching the identifier's permitted character set.
     VALID_CHARS_REGEX = /\A[0-9BCDFGHJKLMNPQRSTVWXYZ]+\z/
 
     # Regular expression for parsing SEDOL components.
@@ -32,6 +36,9 @@ module SecID
     # Weights applied to each character position in the check digit calculation.
     CHARACTER_WEIGHTS = [1, 3, 1, 7, 3, 9].freeze
 
+    # Characters valid in a SEDOL body (alphanumeric excluding vowels).
+    GENERATE_CHARSET = ALPHANUMERIC.grep(VALID_CHARS_REGEX).freeze
+
     # @param sedol [String] the SEDOL string to parse
     def initialize(sedol)
       sedol_parts = parse sedol
@@ -60,6 +67,15 @@ module SecID
       mod10(weighted_sum)
     end
 
+    # Generates a random SEDOL body: 6 characters excluding vowels.
+    #
+    # @param random [Random] source of randomness
+    # @return [String] a 6-character SEDOL body without check digit
+    def self.generate_body(random)
+      random_string(GENERATE_CHARSET, 6, random: random)
+    end
+    private_class_method :generate_body
+
     private
 
     # @return [Hash]

data/lib/sec_id/valoren.rb

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

data/lib/sec_id/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module SecID
-  VERSION = '5.1.0'
+  # Current gem version.
+  VERSION = '6.0.0'
 end

data/lib/sec_id/wkn.rb

@@ -13,9 +13,13 @@ module SecID
   #   SecID::WKN.valid?('514000')  #=> true
   #   SecID::WKN.valid?('CBK100')  #=> true
   class WKN < Base
+    # Human-readable name of the standard.
     FULL_NAME = 'Wertpapierkennnummer'
+    # Valid length(s) of a normalized identifier.
     ID_LENGTH = 6
+    # A representative valid identifier.
     EXAMPLE = '514000'
+    # Pattern matching the identifier's permitted character set.
     VALID_CHARS_REGEX = /\A[0-9A-HJ-NP-Z]+\z/
 
     # Regular expression for parsing WKN components.
@@ -24,6 +28,9 @@ module SecID
       (?<identifier>[0-9A-HJ-NP-Z]{6})
     \z/x
 
+    # Characters valid in a WKN (alphanumeric excluding I and O).
+    GENERATE_CHARSET = ALPHANUMERIC.grep(VALID_CHARS_REGEX).freeze
+
     # @param wkn [String] the WKN string to parse
     def initialize(wkn)
       wkn_parts = parse(wkn)
@@ -40,5 +47,14 @@ module SecID
 
       ISIN.new("#{country_code}000#{identifier}").restore!
     end
+
+    # Generates a random WKN: 6 characters excluding I and O.
+    #
+    # @param random [Random] source of randomness
+    # @return [String] a 6-character WKN
+    def self.generate_body(random)
+      random_string(GENERATE_CHARSET, 6, random: random)
+    end
+    private_class_method :generate_body
   end
 end

data/lib/sec_id.rb

@@ -2,6 +2,11 @@
 
 require 'sec_id/version'
 
+# Toolkit for securities identifiers — validate, normalize, parse, detect, convert,
+# generate, and classify ISIN, CUSIP, CEI, SEDOL, FIGI, LEI, IBAN, CIK, OCC, WKN,
+# Valoren, CFI, FISN, BIC, and DTI.
+#
+# @see https://github.com/svyatov/sec_id
 module SecID
   # Base error class for all SecID errors.
   class Error < StandardError; end
@@ -15,6 +20,9 @@ module SecID
   # Raised for type-specific structural errors (invalid prefix, category, group, BBAN, or date).
   class InvalidStructureError < Error; end
 
+  # Raised when multiple identifier types match and on_ambiguous: :raise is used.
+  class AmbiguousMatchError < Error; end
+
   class << self
     # Looks up an identifier class by its symbol key.
     #
@@ -49,50 +57,103 @@ module SecID
     # @return [Boolean]
     # @raise [ArgumentError] if any key in types is unknown
     def valid?(str, types: nil)
-      return detect(str).any? if types.nil?
+      return detector.matches?(str) if types.nil?
 
       types.any? { |key| self[key].valid?(str) }
     end
 
-    # Parses a string into the most specific matching identifier instance.
-    #
+    # @param text [String, nil] the text to scan
+    # @param types [Array<Symbol>, nil] restrict to specific types
+    # @return [Array<Match>]
+    # @raise [ArgumentError] if any key in types is unknown
+    def extract(text, types: nil)
+      scan(text, types: types).to_a
+    end
+
+    # @param text [String, nil] the text to scan
+    # @param types [Array<Symbol>, nil] restrict to specific types
+    # @return [Enumerator<Match>] if no block given
+    # @yieldparam match [Match]
+    # @raise [ArgumentError] if any key in types is unknown
+    def scan(text, types: nil, &)
+      classes = types&.map { |key| self[key] }
+      scanner.call(text, classes: classes, &)
+    end
+
+    # @param str [String, nil] the identifier string to explain
+    # @param types [Array<Symbol>, nil] restrict to specific types
+    # @return [Hash] hash with :input and :candidates keys
+    def explain(str, types: nil)
+      input = str.to_s.strip
+      target_keys = types || identifier_list.map { |k| k.short_name.downcase.to_sym }
+      candidates = target_keys.map do |key|
+        instance = self[key].new(input)
+        { type: key, valid: instance.valid?, errors: instance.errors.details }
+      end
+      { input: input, candidates: candidates }
+    end
+
     # @param str [String, nil] the identifier string to parse
     # @param types [Array<Symbol>, nil] restrict to specific types (e.g. [:isin, :cusip])
-    # @return [SecID::Base, nil] a valid identifier instance, or nil if no match
-    # @raise [ArgumentError] if any key in types is unknown
-    def parse(str, types: nil)
-      types.nil? ? parse_any(str) : parse_from(str, types)
+    # @param on_ambiguous [:first, :raise, :all] how to handle multiple matches
+    # @return [SecID::Base, nil, Array<SecID::Base>] depends on on_ambiguous mode
+    # @raise [AmbiguousMatchError] when on_ambiguous: :raise and multiple types match
+    def parse(str, types: nil, on_ambiguous: :first)
+      case on_ambiguous
+      when :first then types.nil? ? parse_any(str) : parse_from(str, types)
+      when :raise then parse_strict(str, types)
+      when :all   then parse_all(str, types)
+      else raise ArgumentError, "Unknown on_ambiguous mode: #{on_ambiguous.inspect}"
+      end
     end
 
-    # Parses a string into the most specific matching identifier instance, raising on failure.
-    #
     # @param str [String, nil] the identifier string to parse
     # @param types [Array<Symbol>, nil] restrict to specific types (e.g. [:isin, :cusip])
-    # @return [SecID::Base] a valid identifier instance
+    # @param on_ambiguous [:first, :raise, :all] how to handle multiple matches
+    # @return [SecID::Base, Array<SecID::Base>] depends on on_ambiguous mode
     # @raise [InvalidFormatError] if no matching identifier type is found
-    # @raise [ArgumentError] if any key in types is unknown
-    def parse!(str, types: nil)
-      parse(str, types: types) || raise(InvalidFormatError, parse_error_message(str, types))
+    # @raise [AmbiguousMatchError] when on_ambiguous: :raise and multiple types match
+    def parse!(str, types: nil, on_ambiguous: :first)
+      result = parse(str, types: types, on_ambiguous: on_ambiguous)
+
+      if on_ambiguous == :all
+        raise(InvalidFormatError, parse_error_message(str, types)) if result.empty?
+
+        return result
+      end
+
+      result || raise(InvalidFormatError, parse_error_message(str, types))
+    end
+
+    # Generates a new, format-valid identifier instance of the given type.
+    #
+    # @note Generated identifiers are valid in format only — they are not real,
+    #   registered securities.
+    #
+    # @param key [Symbol] identifier type (e.g. :isin, :cusip)
+    # @param random [Random] seedable source for reproducible output
+    # @return [SecID::Base] a generated, format-valid instance of the type mapped to `key`
+    #   (e.g. {SecID::ISIN} for `:isin`)
+    # @raise [ArgumentError] if key is unknown
+    def generate(key, random: Random.new)
+      self[key].generate(random: random)
     end
 
     private
 
-    # @param klass [Class] the identifier class to register
     # @return [void]
     def register_identifier(klass)
       key = klass.name.split('::').last.downcase.to_sym
       identifier_map[key] = klass
       identifier_list << klass
       @detector = nil
+      @scanner = nil
     end
 
-    # @return [SecID::Base, nil]
     def parse_any(str)
-      key = detect(str).first
-      key && self[key].new(str)
+      detector.first_match(str)
     end
 
-    # @return [SecID::Base, nil]
     def parse_from(str, types)
       types.each do |key|
         instance = self[key].new(str)
@@ -101,36 +162,49 @@ module SecID
       nil
     end
 
-    # @return [String]
-    def parse_error_message(str, types)
-      base = "No matching identifier type found for #{str.to_s.strip.inspect}"
-      types ? "#{base} among #{types.inspect}" : base
+    def parse_strict(str, types)
+      candidates = resolve_candidates(str, types)
+      raise AmbiguousMatchError, ambiguous_message(str, candidates) if candidates.size > 1
+
+      candidates.first && self[candidates.first].new(str)
     end
 
-    # @return [Detector]
-    def detector
-      @detector ||= Detector.new(identifier_list)
+    def parse_all(str, types)
+      resolve_candidates(str, types).map { |key| self[key].new(str) }
     end
 
-    # @return [Hash{Symbol => Class}]
-    def identifier_map
-      @identifier_map ||= {}
+    # @return [Array<Symbol>]
+    def resolve_candidates(str, types)
+      types ? types.select { |key| self[key].valid?(str) } : detect(str)
     end
 
-    # @return [Array<Class>]
-    def identifier_list
-      @identifier_list ||= []
+    # @return [String]
+    def ambiguous_message(str, candidates)
+      "Ambiguous identifier #{str.to_s.strip.inspect}: matches #{candidates.inspect}"
+    end
+
+    # @return [String]
+    def parse_error_message(str, types)
+      base = "No matching identifier type found for #{str.to_s.strip.inspect}"
+      types ? "#{base} among #{types.inspect}" : base
     end
+
+    def detector = @detector ||= Detector.new(identifier_list)
+    def scanner = @scanner ||= Scanner.new(identifier_list)
+    def identifier_map = @identifier_map ||= {}
+    def identifier_list = @identifier_list ||= []
   end
 end
 
+require 'sec_id/deep_freeze'
 require 'sec_id/errors'
-require 'sec_id/concerns/identifier_metadata'
 require 'sec_id/concerns/normalizable'
 require 'sec_id/concerns/validatable'
 require 'sec_id/concerns/checkable'
+require 'sec_id/concerns/generatable'
 require 'sec_id/base'
 require 'sec_id/detector'
+require 'sec_id/scanner'
 require 'sec_id/isin'
 require 'sec_id/cusip'
 require 'sec_id/sedol'
@@ -144,3 +218,9 @@ require 'sec_id/valoren'
 require 'sec_id/cei'
 require 'sec_id/cfi'
 require 'sec_id/fisn'
+require 'sec_id/bic'
+require 'sec_id/dti'
+
+# Auto-activate the ActiveModel validator inside Rails; a no-op everywhere else (keeps the
+# default require zero-dependency). See SecID::Railtie and lib/sec_id/active_model.rb.
+require 'sec_id/railtie' if defined?(Rails::Railtie)

data/sec_id.gemspec

@@ -10,19 +10,25 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Leonid Svyatov']
   spec.email         = ['leonid@svyatov.ru']
 
-  spec.summary       = 'Validate securities identification numbers with ease!'
-  spec.description   = 'Validate, calculate check digits, and parse components of securities identifiers. ' \
-                       'Supports ISIN, CUSIP, CEI, SEDOL, FIGI, LEI, IBAN, CIK, OCC, WKN, Valoren, CFI, ' \
-                       'and FISN standards.'
+  spec.summary       = 'A Ruby toolkit for securities identifiers — validate, parse, normalize, detect, convert, ' \
+                       'generate, and classify.'
+  spec.description   = 'Validate, normalize, parse, convert, generate, and classify securities identifiers. ' \
+                       'Auto-detect identifier type from any string. Calculate and restore check digits. Generate ' \
+                       'format-valid identifiers as test fixtures. Decode CFI codes to full ISO 10962:2021 ' \
+                       'classifications. Includes an opt-in ActiveModel/Rails validator that adds no runtime ' \
+                       'dependency. Supports ISIN, CUSIP, CEI, SEDOL, FIGI, LEI, IBAN, CIK, OCC, WKN, Valoren, ' \
+                       'CFI, FISN, BIC, and DTI.'
   spec.homepage      = 'https://github.com/svyatov/sec_id'
   spec.license       = 'MIT'
 
   spec.required_ruby_version = '>= 3.2.0'
 
   spec.require_paths = ['lib']
-  spec.files = Dir['lib/**/*.rb'] + %w[CHANGELOG.md LICENSE.txt MIGRATION.md README.md sec_id.gemspec]
+  spec.files = Dir['lib/**/*.rb'] + Dir['sig/**/*'] +
+               %w[.yardopts CHANGELOG.md LICENSE.txt MIGRATION.md README.md sec_id.gemspec]
 
   spec.metadata['rubygems_mfa_required'] = 'true'
+  spec.metadata['documentation_uri'] = 'https://rubydoc.info/gems/sec_id'
   spec.metadata['source_code_uri'] = 'https://github.com/svyatov/sec_id'
   spec.metadata['changelog_uri'] = 'https://github.com/svyatov/sec_id/blob/main/CHANGELOG.md'
   spec.metadata['bug_tracker_uri'] = 'https://github.com/svyatov/sec_id/issues'

data/sig/manifest.yaml

@@ -0,0 +1,8 @@
+# Standard-library signatures these RBS files reference. Consumers' RBS/Steep
+# load these automatically when they depend on sec_id. (The gem has no runtime
+# gem dependencies, so none are auto-derived from the gemspec.)
+#
+# Set (ISIN, SEDOL, FIGI, Valoren, BIC) is a core class in rbs 4.0 — always
+# loaded, so it needs no manifest entry.
+dependencies:
+  - name: date  # Date in OCC

data/sig/sec_id/base.rbs

@@ -0,0 +1,72 @@
+module SecID
+  # Accepted raw input for parsing/validating an identifier: a String, an Integer
+  # (Valoren/CIK/CUSIP accept numeric input), or nil.
+  type input = String | Integer | nil
+
+  # The class-object surface the concern ClassMethods modules call through `self`
+  # once extended onto an identifier class (they construct instances via `new`).
+  interface _IdentifierClass
+    def new: (SecID::input) -> Base
+  end
+
+  # Base class for securities identifiers, providing a common interface for
+  # validation, normalization, parsing, and generation.
+  class Base
+    include Normalizable
+    include Validatable
+    include Generatable
+    extend Normalizable::ClassMethods
+    extend Validatable::ClassMethods
+    extend Generatable::ClassMethods
+
+    # Metadata constants each subclass overrides with its concrete shape. Declared
+    # here (as the widest shape) so the shared concern method bodies type-check.
+    FULL_NAME: String
+    ID_LENGTH: Integer | ::Range[Integer] | ::Array[Integer]
+    EXAMPLE: String
+    VALID_CHARS_REGEX: ::Regexp
+    ID_REGEX: ::Regexp
+
+    attr_reader full_id: String
+    # Reader is nilable (nil for invalid input, checked by `valid_format?`); the ivar is
+    # typed `untyped` because subclasses use `@identifier` as non-nil after validation and
+    # RBS forbids narrowing an inherited ivar's type.
+    def identifier: () -> String?
+
+    def self.short_name: () -> String
+    def self.full_name: () -> String
+    def self.id_length: () -> (Integer | ::Range[Integer] | ::Array[Integer])
+    def self.length_values: () -> (::Array[Integer] | ::Range[Integer])
+    def self.length_specificity: () -> (Integer | Float | nil)
+    def self.example: () -> String
+    def self.has_check_digit?: () -> bool
+    def self.inherited: (singleton(Base) subclass) -> void
+
+    def initialize: (SecID::input _sec_id_number) -> void
+
+    def ==: (Base other) -> bool
+    alias eql? ==
+    def hash: () -> Integer
+    def to_h: () -> Hash[Symbol, untyped]
+    def as_json: (*untyped) -> Hash[Symbol, untyped]
+
+    # Check-digit surface. Only the types that `include Checkable` implement these
+    # (they raise/NoMethodError otherwise); declared on Base so `Generatable#generate`
+    # and `Checkable::ClassMethods` type-check without narrowing on `has_check_digit?`.
+    def restore: () -> String
+    def restore!: () -> self
+    def calculate_check_digit: () -> (Integer | String)
+
+    def comparison_id: () -> String
+
+    private
+
+    def components: () -> Hash[Symbol, untyped]
+    def parse: (SecID::input sec_id_number) -> (::MatchData | ::Hash[Symbol, untyped])
+
+    @full_id: String
+    @identifier: untyped
+    self.@short_name: String
+    self.@has_check_digit: bool
+  end
+end

data/sig/sec_id/bic/country_codes.rbs

@@ -0,0 +1,5 @@
+module SecID
+  class BIC < Base
+    COUNTRY_CODES: Set[String]
+  end
+end

data/sig/sec_id/bic.rbs

@@ -0,0 +1,30 @@
+module SecID
+  # Business Identifier Code (BIC / SWIFT code).
+  class BIC < Base
+    FULL_NAME: String
+    ID_LENGTH: Array[Integer]
+    EXAMPLE: String
+    VALID_CHARS_REGEX: ::Regexp
+    ID_REGEX: ::Regexp
+
+    def self.countries: () -> Array[String]
+
+    attr_reader bank_code: String?
+    attr_reader country_code: String?
+    attr_reader location_code: String?
+    attr_reader branch_code: String?
+
+    def initialize: (SecID::input bic) -> void
+    private def self.generate_body: (Random random) -> String
+
+    private
+
+    def components: () -> Hash[Symbol, untyped]
+    def valid_format?: () -> bool
+    def detect_errors: () -> Array[Symbol]
+    def validation_message: (Symbol code) -> String?
+    def recognized_country?: () -> bool
+
+    self.@countries: Array[String]
+  end
+end

data/sig/sec_id/cei.rbs

@@ -0,0 +1,26 @@
+module SecID
+  # CUSIP Entity Identifier (CEI).
+  class CEI < Base
+    include Checkable
+    extend Checkable::ClassMethods
+
+    FULL_NAME: String
+    ID_LENGTH: Integer
+    EXAMPLE: String
+    VALID_CHARS_REGEX: ::Regexp
+    ID_REGEX: ::Regexp
+
+    attr_reader prefix: String?
+    attr_reader numeric: String?
+    attr_reader entity_id: String?
+
+    def initialize: (SecID::input cei) -> void
+    def calculate_check_digit: () -> Integer
+    def self.check_digit: (SecID::input id) -> Integer
+    private def self.generate_body: (Random random) -> String
+
+    private
+
+    def components: () -> Hash[Symbol, untyped]
+  end
+end

data/sig/sec_id/cfi/attribute_set.rbs

@@ -0,0 +1,68 @@
+# Generated by `rake sig:cfi` from SecID::CFI::Tables. Do not edit by hand.
+module SecID
+  class CFI < Base
+    # The ordered collection of decoded attribute Fields.
+    class AttributeSet
+      include Enumerable[Field]
+
+      # `fields` is typed `untyped` because `#initialize` calls
+      # `define_singleton_method(field.meaning)` and `field.meaning` is nilable.
+      def initialize: (untyped fields) -> void
+      def each: () { (Field) -> void } -> self
+              | () -> Enumerator[Field, self]
+      def []: (Symbol meaning) -> Field?
+      def empty?: () -> bool
+      def to_h: () -> Hash[untyped, untyped]
+      def as_json: (*untyped) -> Hash[Symbol, untyped]
+
+      # Per-meaning readers — the union of every attribute meaning. Each instance
+      # only answers the meanings actually present; an absent one raises
+      # NoMethodError at runtime. Use #[] for the presence-uncertain path.
+      def asset_class: () -> Field
+      def assets: () -> Field
+      def barrier_dependency: () -> Field
+      def calculation_frequency: () -> Field
+      def call_put: () -> Field
+      def closed_open: () -> Field
+      def components: () -> Field
+      def composition: () -> Field
+      def currency: () -> Field
+      def delivery: () -> Field
+      def distribution: () -> Field
+      def distribution_policy: () -> Field
+      def equity_type: () -> Field
+      def exercise_style: () -> Field
+      def form: () -> Field
+      def further_grouping: () -> Field
+      def guarantee: () -> Field
+      def income: () -> Field
+      def interest_rate_type: () -> Field
+      def interest_type: () -> Field
+      def investment_strategy: () -> Field
+      def issuer_type: () -> Field
+      def long_short: () -> Field
+      def notional: () -> Field
+      def option_style: () -> Field
+      def ownership_restrictions: () -> Field
+      def payment_status: () -> Field
+      def redemption: () -> Field
+      def repayment: () -> Field
+      def return_trigger: () -> Field
+      def return_type: () -> Field
+      def security_type: () -> Field
+      def standardized: () -> Field
+      def strategy_style: () -> Field
+      def termination: () -> Field
+      def type: () -> Field
+      def underlying: () -> Field
+      def underlying_assets: () -> Field
+      def underlying_fund_type: () -> Field
+      def valuation: () -> Field
+      def voting_right: () -> Field
+      def warrant_type: () -> Field
+      def weighting: () -> Field
+
+      @fields: Array[Field]
+    end
+  end
+end

data/sig/sec_id/cfi/classification.rbs

@@ -0,0 +1,23 @@
+module SecID
+  class CFI < Base
+    # The decoded ISO 10962:2021 classification of a valid CFI, built by {CFI#decode}.
+    class Classification
+      attr_reader category: Field
+      attr_reader group: Field
+      attr_reader attributes: AttributeSet
+
+      def initialize: (String category_code, String group_code, Array[String] letters) -> void
+      def to_s: () -> String
+      def to_h: () -> Hash[Symbol, untyped]
+      def as_json: (*untyped) -> Hash[Symbol, untyped]
+
+      private
+
+      def build_category: (String code) -> Field
+      def build_group: (String category_code, String code) -> Field
+      def build_attributes: (String category_code, String group_code, Array[String] letters) -> AttributeSet
+      def build_attribute: (untyped position, String letter) -> Field
+      def decode_value: (untyped value_map, String letter) -> [Symbol, String]
+    end
+  end
+end