sec_id 4.4.1 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20409e751f968646b7679c2b252f4e1271be9bfd718594623cf2ac7d45c11db3
-  data.tar.gz: c65e3bcb5f6196543873c19ed845c29b77e4caec3c473bb74c7457eb42ab0369
+  metadata.gz: 0b0779f0d2735ded84be536bcc9690a4b106c729b03aab007a0458b6512020e8
+  data.tar.gz: 3b4d99c3534856e5e05ff68cec5355f3c7a2665e2854dad5415815e275a734b1
 SHA512:
-  metadata.gz: ea451044dbeee4c685ea90300cdb4b3f4704b58a9966cdae579992b969bf79bab5a0781693ec4f59a7ec32050a2b197827f6b932eb460b7cfc5e145636815d43
-  data.tar.gz: e7c691adedcdc482580adc6ccd11fa445dcd6414a56ed5b0f31c1496fc54af0eece6259791a791b9c44682b0204b6e4c7d01befe664fa79f63d00ff11efa9e22
+  metadata.gz: ec036b3fbf2c3d7a89ec823fed2dea6c8cb92be1ede8792bae623c1474454141a3dcc3da27d14c5e3734b050dd95b25672552fc9f4c6983bc68d807a7493d392
+  data.tar.gz: 397e7c17dd46c8aad067262289307317e04cdba4fac65d890aa3e3ff1a1b9ecf175ab916d9600dab7a7a5d4629b54f7750fd40f11c79ed220d3bca339a210d0c

data/CHANGELOG.md

@@ -8,6 +8,62 @@ and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
 ## [Unreleased]
 
+## [5.1.0] - 2026-02-19
+
+### Added
+
+- `#==`, `#eql?`, and `#hash` methods on all identifier types — two instances of the same type with the same normalized form are equal and usable as Hash keys / in Sets
+- `#to_h` method on all identifier types for consistent hash serialization — returns `{ type:, full_id:, normalized:, valid:, components: }` with type-specific component hashes (e.g. ISIN: `country_code`, `nsin`, `check_digit`)
+- `#to_pretty_s` and `.to_pretty_s` display formatting methods on all identifier types, returning a human-readable string or `nil` for invalid input — with type-specific formats for IBAN (4-char groups), LEI (4-char groups), ISIN (CC + NSIN + CD), CUSIP (cusip6 + issue + CD), FIGI (prefix+G + random + CD), OCC (space-separated components), and Valoren (thousands grouping)
+- Lookup service integration guides and runnable examples for OpenFIGI, SEC EDGAR, GLEIF, and Eurex APIs (`docs/guides/`, `examples/`)
+- GitHub community standards files: Code of Conduct, Contributing guide, Security policy, issue templates, and PR template
+
+## [5.0.0] - 2026-02-17
+
+### Added
+
+- `Validatable`, `Normalizable`, and `IdentifierMetadata` concerns extracted from `Base`, making each responsibility independently includable
+- `#validate` and `.validate` methods on all identifier types that eagerly trigger + cache errors and return `self`/instance
+- `#validate!` and `.validate!` methods that raise `InvalidFormatError`, `InvalidCheckDigitError`, or `InvalidStructureError` on validation failure, returning self/instance on success
+- Rails-like `#errors` API returning `Errors` with `details`, `messages`, `none?`, `any?`, `empty?`, `size`, `each`, and `to_a` on all identifier classes, with type-specific error detection for check digits, FIGI prefixes, CFI categories/groups, IBAN BBAN format, and OCC dates
+- `#restore` instance method on check-digit identifiers returning the full identifier string without mutation
+- `.restore` class method on check-digit identifiers returning the full identifier string
+- `SecID.parse(str, types: nil)` and `SecID.parse!(str, types: nil)` methods that return a typed identifier instance for the most specific match, with optional type filtering
+- `SecID.valid?(str, types: nil)` method for quick boolean validation against all or specific identifier types
+- `SecID.detect(str)` method that identifies all matching identifier types for a given string, returning symbols sorted by specificity
+- Metadata registry: `SecID.identifiers` returns all identifier classes, `SecID[:isin]` looks up by symbol key
+- Metadata class methods on all identifiers: `short_name`, `full_name`, `id_length`, `example`, `has_check_digit?`
+- `#normalized` and `#normalize` instance methods on all identifier types returning the canonical string form
+- `#normalize!` instance method on all identifier types that mutates `full_id` to canonical form and returns `self`
+- `.normalize(id)` class method on all identifier types that strips separators, upcases, validates, and returns the canonical string
+- `SEPARATORS` constant in `Normalizable` (`/[\s-]/`) included in `Base`, with type-specific overrides for OCC and FISN (`/-/`)
+
+### Changed
+
+- **BREAKING:** Minimum Ruby version raised from 3.1 to 3.2 (Ruby 3.1 reached EOL on 2025-03-31)
+- **BREAKING:** `#restore!` now returns `self` instead of a string; use `#restore` for the string return value
+- **BREAKING:** `.restore!` now returns the restored instance instead of a string; use `.restore` for the string return value
+- **BREAKING:** `#normalize!` on CIK, OCC, and Valoren now returns `self` instead of a string; use `#normalized` to get the canonical string
+- **BREAKING:** Class-level `.normalize!` on CIK, OCC, and Valoren replaced by `.normalize` (non-bang) which returns the canonical string
+- **BREAKING:** `Base#parse` always upcases input; the `upcase` keyword parameter is removed
+- **BREAKING:** `#full_number` renamed to `#full_id` on all identifier types
+- **BREAKING:** Ruby module renamed from `SecId` to `SecID` (e.g. `SecId::ISIN` → `SecID::ISIN`)
+- Luhn helper methods in Checkable are now private (implementation detail)
+
+### Removed
+
+- Class-level `.normalize!` on CIK, OCC, and Valoren — replaced by `.normalize`
+- `upcase` keyword parameter from `Base#parse`
+- `#valid_format?` instance method (now private) and `.valid_format?` class method
+- `OCC#full_symbol` method — use `#full_id` instead
+
+### Fixed
+
+- `to_str` now always returns the same value as `to_s` across all identifier types — previously LEI, IBAN, and Checkable identifiers could return divergent strings due to Ruby `alias` resolving to the parent class method
+- OCC `#date` memoization for invalid dates — previously re-attempted parsing on every call instead of caching `nil`
+- LEI `restore` and `to_s` now correctly pad single-digit check digits to 2 characters
+- `Valoren#to_isin` no longer mutates the source instance
+
 ## [4.4.1] - 2026-02-05
 
 ### Fixed
@@ -115,7 +171,7 @@ and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
 ### Added
 
-- SEDOL numbers support: `SecId::SEDOL`
+- SEDOL numbers support: `SecID::SEDOL`
 
 ### Changed
 
@@ -135,7 +191,7 @@ and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
 ### Added
 
-- CUSIP numbers support: `SecId::CUSIP`
+- CUSIP numbers support: `SecID::CUSIP`
 - CHANGELOG.md file added
 
 ### Changed
@@ -146,4 +202,4 @@ and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
 ### Added
 
-- ISIN numbers support: `SecId::ISIN`
+- ISIN numbers support: `SecID::ISIN`

data/MIGRATION.md

@@ -0,0 +1,257 @@
+# Upgrading to SecID 5.0
+
+This guide covers all breaking changes when upgrading from SecID 4.x to 5.0.
+
+## Requirements
+
+- **Ruby 3.2+** (was 3.1+)
+
+## Quick Reference
+
+| What changed | Search pattern | Replacement |
+|---|---|---|
+| Module rename | `SecId::` | `SecID::` |
+| Attribute rename | `.full_number` | `.full_id` |
+| OCC method removed | `.full_symbol` | `.full_id` |
+| ValidationResult rename | `SecID::ValidationResult` | `SecID::Errors` |
+| `ValidationResult#valid?` | `result.valid?` | `result.none?` |
+| `.validate` return type | `Klass.validate(id)` returns `ValidationResult` | `Klass.validate(id)` returns instance; use `.errors` for errors |
+| `EXCEPTION_MAP` rename | `Base::EXCEPTION_MAP` | `Validatable::ERROR_MAP` |
+| `.exception_for_error` rename | `.exception_for_error(code)` | `.error_class_for(code)` |
+| `format_errors` rename (private) | `def format_errors` | `def detect_errors` |
+| `validation_errors` rename (private) | `def validation_errors` | `def error_codes` |
+| Instance `restore!` return | `= obj.restore!` | `obj.restore!` (returns `self`) or `= obj.restore` (returns string) |
+| Class `restore!` return | `= Klass.restore!(id)` | `Klass.restore!(id)` (returns instance) or `= Klass.restore(id)` (returns string) |
+| Instance `normalize!` return | `= obj.normalize!` | `obj.normalize!` (returns `self`) or `= obj.normalized` (returns string) |
+| Class `normalize!` removed | `.normalize!(id)` | `.normalize(id)` |
+| `valid_format?` removed | `.valid_format?` | `.valid?` or `.validate` |
+| `parse` upcase param | `parse(id, upcase: false)` | `parse(id)` (always upcases) |
+
+## Step-by-Step
+
+### 1. Update Gemfile
+
+```ruby
+gem 'sec_id', '~> 5.0'
+```
+
+Then run `bundle update sec_id`.
+
+### 2. Rename module: SecId → SecID
+
+The module was renamed to match the conventional acronym casing.
+
+```ruby
+# Before
+SecId::ISIN.valid?('US5949181045')
+
+# After
+SecID::ISIN.valid?('US5949181045')
+```
+
+Find all occurrences:
+
+```bash
+grep -r 'SecId[^A-Z]' app/ lib/ spec/
+```
+
+### 3. Rename attribute: full_number → full_id
+
+```ruby
+# Before
+isin.full_number  # => 'US5949181045'
+
+# After
+isin.full_id      # => 'US5949181045'
+```
+
+If you used `OCC#full_symbol`, replace it with `#full_id` as well.
+
+Find all occurrences:
+
+```bash
+grep -rE '\.(full_number|full_symbol)\b' app/ lib/ spec/
+```
+
+### 4. Update restore! usage (returns self now)
+
+In v4, both instance and class `restore!` returned a string. In v5, they return `self`/instance for chaining. Use `restore` (without bang) to get the string.
+
+```ruby
+# Before (v4) — restore! returned a string
+id_string = isin.restore!
+
+# After (v5) — choose one:
+id_string = isin.restore        # string return (new method)
+isin.restore!                   # mutates and returns self
+
+# Class-level
+id_string = SecID::ISIN.restore('US594918104')    # returns string
+instance  = SecID::ISIN.restore!('US594918104')   # returns instance
+```
+
+### 5. Update normalize! usage (returns self now)
+
+Applies to CIK, OCC, and Valoren — the only types with normalization in v4.
+
+```ruby
+# Before (v4) — normalize! returned a string
+normalized = cik.normalize!
+
+# After (v5) — choose one:
+normalized = cik.normalized     # string return (new method)
+cik.normalize!                  # mutates and returns self
+
+# Class-level .normalize! removed — use .normalize
+# Before
+SecId::CIK.normalize!('1094517')
+
+# After
+SecID::CIK.normalize('1094517')   # => '0001094517'
+```
+
+Note: In v5, all identifier types support normalization, not just CIK/OCC/Valoren.
+
+### 6. Remove calls to deleted methods
+
+**`valid_format?` / `.valid_format?`** — removed from public API. Use `valid?` for boolean checks or `errors` for details:
+
+```ruby
+# Before
+SecId::ISIN.valid_format?('US5949181045')
+
+# After
+SecID::ISIN.valid?('US5949181045')
+# or for detailed errors:
+SecID::ISIN.validate('US5949181045').messages
+```
+
+**`OCC#full_symbol`** — use `#full_id`:
+
+```ruby
+# Before
+occ.full_symbol
+
+# After
+occ.full_id
+```
+
+### 7. Update parse calls in custom subclasses
+
+If you subclass `SecID::Base` and call `parse` with `upcase: false`, remove that parameter. `parse` now always upcases input.
+
+```ruby
+# Before
+parse(id, upcase: false)
+
+# After
+parse(id)
+```
+
+### 8. Handle now-private Luhn helpers
+
+If you subclass `SecID::Base` with `Checkable` and call Luhn helper methods directly (`luhn_sum_double_add_double`, `luhn_sum_indexed`, `luhn_sum_standard`, etc.), these are now private. Use `calculate_check_digit` instead.
+
+### 9. Update exception handling
+
+The module rename affects exception class references:
+
+```ruby
+# Before
+rescue SecId::InvalidFormatError
+
+# After
+rescue SecID::InvalidFormatError
+```
+
+v5 adds two new exception types for more granular error handling:
+
+- `SecID::InvalidCheckDigitError` — raised when check digit doesn't match
+- `SecID::InvalidStructureError` — raised for type-specific structural errors (FIGI prefix, CFI category/group, IBAN BBAN, OCC date)
+
+Both inherit from `SecID::Error`, so existing `rescue SecID::Error` blocks still work. Optionally catch the specific types:
+
+```ruby
+begin
+  SecID::ISIN.new('US5949181040').validate!
+rescue SecID::InvalidCheckDigitError => e
+  # handle bad check digit specifically
+rescue SecID::InvalidFormatError => e
+  # handle format errors
+end
+```
+
+### 10. Rename ValidationResult to Errors
+
+`ValidationResult` has been renamed to `Errors`. The `valid?` method is replaced by `none?` for clearer semantics.
+
+```ruby
+# Before
+result = SecId::ISIN.new('US5949181045').errors
+result.valid?  # => true
+
+# After
+result = SecID::ISIN.new('US5949181045').errors
+result.none?   # => true
+```
+
+Find all occurrences:
+
+```bash
+grep -rE 'ValidationResult|\.valid\?' app/ lib/ spec/
+```
+
+### 11. Update .validate usage (returns instance now)
+
+`.validate` now returns the identifier instance (with errors cached) instead of a `ValidationResult`/`Errors` object.
+
+```ruby
+# Before (v4)
+result = SecId::ISIN.validate('US5949181045')  # => #<SecId::ValidationResult>
+result.valid?
+
+# After (v5)
+instance = SecID::ISIN.validate('US5949181045')  # => #<SecID::ISIN>
+instance.errors.none?
+```
+
+### 12. Update subclass overrides (private API)
+
+If you subclass `SecID::Base` and override private validation methods:
+
+```ruby
+# Before
+def format_errors       # renamed
+def validation_errors   # renamed
+
+# After
+def detect_errors
+def error_codes
+```
+
+If you reference `EXCEPTION_MAP` or `exception_for_error`:
+
+```ruby
+# Before
+Base::EXCEPTION_MAP
+Klass.exception_for_error(:code)
+
+# After
+Validatable::ERROR_MAP
+Klass.error_class_for(:code)
+```
+
+### 13. Explore new features (optional)
+
+v5 adds several features beyond the breaking changes:
+
+- **Structured validation** — `#errors` returns an `Errors` object with `details`, `messages`, `none?`, `any?`, `empty?`, `size`, `each`
+- **Eager validation** — `#validate` / `.validate` triggers validation and returns the instance
+- **Fail-fast validation** — `#validate!` raises descriptive exceptions
+- **Type detection** — `SecID.detect('US5949181045')` returns `[:isin]`
+- **Universal parsing** — `SecID.parse('US5949181045')` returns a typed instance
+- **Quick validation** — `SecID.valid?('US5949181045')` validates against all types
+- **Metadata registry** — `SecID.identifiers`, `SecID[:isin]`, `SecID::ISIN.full_name`
+- **Universal normalization** — all types now support `#normalized`, `#normalize!`, `.normalize`
+
+See [README.md](README.md) for full usage examples.