sec_id 5.2.0 → 6.1.0

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.2.0'
+  # Current gem version.
+  VERSION = '6.1.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
@@ -52,7 +57,7 @@ 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
@@ -80,7 +85,7 @@ module SecID
     # @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 }
+      target_keys = types || identifier_list.map(&:type_key)
       candidates = target_keys.map do |key|
         instance = self[key].new(input)
         { type: key, valid: instance.valid?, errors: instance.errors.details }
@@ -120,20 +125,32 @@ module SecID
       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
 
     # @return [void]
     def register_identifier(klass)
-      key = klass.name.split('::').last.downcase.to_sym
-      identifier_map[key] = klass
+      identifier_map[klass.type_key] = klass
       identifier_list << klass
       @detector = nil
       @scanner = nil
     end
 
     def parse_any(str)
-      key = detect(str).first
-      key && self[key].new(str)
+      detector.first_match(str)
     end
 
     def parse_from(str, types)
@@ -178,11 +195,12 @@ module SecID
   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'
@@ -199,3 +217,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       = 'A Ruby toolkit for securities identifiers — validate, parse, normalize, detect, and convert.'
-  spec.description   = 'Validate, normalize, parse, and convert securities identifiers. Auto-detect identifier ' \
-                       'type from any string. Calculate and restore check digits. Supports ISIN, CUSIP, CEI, ' \
-                       'SEDOL, FIGI, LEI, IBAN, CIK, OCC, WKN, Valoren, CFI, and FISN.'
+  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,78 @@
+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.type_key: () -> Symbol
+    # `@api private` in YARD, but public here: Detector and Scanner call it from outside.
+    def self.detection_priority: () -> Array[Integer | Float | nil]
+    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]
+    def deconstruct_keys: (::Array[Symbol]? _keys) -> 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
+    self.@type_key: Symbol
+    self.@detection_priority: Array[Integer | Float | nil]
+  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