minting 2.1.0 → 2.2.0

data/lib/minting/aliases.rb

@@ -1,22 +1,22 @@
 # frozen_string_literal: true
 
 # @!parse
-#   # Top-level alias for {Money::Currency}, opt-in via +require 'minting/aliases'+.
-#   Currency = Money::Currency
+#   # Top-level alias for {Mint::Currency}, opt-in via +require 'minting/aliases'+.
+#   Currency = Mint::Currency
 
-# Top-level alias for {Money::Currency}, opt-in via +require 'minting/aliases'+.
+# Top-level alias for {Mint::Currency}, opt-in via +require 'minting/aliases'+.
 #
 # {::Currency} is **not** auto-bound by `require 'minting'` because
 # application domain models are commonly named +Currency+ (e.g. a Rails
 # model). Load this file explicitly to opt in.
 #
 # If {::Currency} is already defined, a warning is emitted and the existing
-# constant is preserved — use {Money::Currency} explicitly in that case.
+# constant is preserved — use {Mint::Currency} explicitly in that case.
 #
-# @see Money::Currency
+# @see Mint::Currency
 
-Currency = Money::Currency unless defined?(Currency)
+Currency = Mint::Currency unless defined?(Currency)
 
-if Currency != Money::Currency
-  warn "minting: top-level Currency was already defined (#{Currency}); skipping alias. Use Money::Currency"
+if Currency != Mint::Currency
+  warn "minting: top-level Currency was already defined (#{Currency}); skipping alias. Use Mint::Currency"
 end

data/lib/minting/currency/registry.rb

@@ -124,11 +124,8 @@ module Mint
   # @raise [Mint::UnknownCurrency] if the currency can't be resolved
   def Currency.zero(currency) = Registry.zero_for(Currency.resolve!(currency))
 
-  # --- @api private ---
-
   # Returns the frozen hash of all built-in ISO 4217 world currencies.
   #
   # @return [Hash{String => Currency}] ISO-4217 world currencies mapped by code
-  # @api private
   def Currency.world_currencies = Registry.world_currencies
 end

data/lib/minting/mint/dsl/numeric.rb

@@ -11,11 +11,16 @@ class Numeric
   # @return [Money] self interpreted as EUR
   def euros = Mint::Money.from(self, 'EUR')
 
-  # @param currency [String, Symbol, Currency] target currency
+  # @param currency [String, Currency] target currency
   # @return [Money] self interpreted as the given currency
   def to_money(currency) = Mint::Money.from(self, currency)
 
   alias dollar dollars
   alias euro euros
-  alias mint to_money
+
+  # @deprecated Use +to_money+ instead.
+  def mint(currency)
+    warn 'DEPRECATION: Numeric#mint is deprecated; use #to_money instead.', uplevel: 1
+    to_money(currency)
+  end
 end

data/lib/minting/mint/dsl/string.rb

@@ -4,7 +4,7 @@
 class String
   # Parses self as a numeric string and creates a Money in the given currency.
   #
-  # @param currency [String, Symbol, Currency] target currency
+  # @param currency [String, Currency] default currency when self has no currency marker
   # @return [Money]
   def to_money(currency = nil) = Mint::Money.parse(self, currency)
 end

data/lib/minting/mint/mint.rb

@@ -11,6 +11,8 @@ module Mint
 
   # Creates a new {Money} instance with the given amount and currency code.
   #
+  # @deprecated Use {Money.from} instead.
+  #
   # @param amount [Numeric] the financial value
   # @param currency_code [String, Currency, Money, nil] Currency code, object,
   #   Money whose currency to reuse, or +nil+. Passed through
@@ -20,5 +22,8 @@ module Mint
   # @raise [ArgumentError] if the amount is not a Numeric
   # @raise [Mint::UnknownCurrency] if the currency code is not registered.
   #   +Mint::UnknownCurrency+ inherits from +ArgumentError+.
-  def self.money(amount, currency_code) = Money.from(amount, currency_code)
+  def self.money(amount, currency_code)
+    warn 'DEPRECATION: Mint.money is deprecated; use Money.from instead.', uplevel: 1
+    Money.from(amount, currency_code)
+  end
 end

data/lib/minting/mint/registry/crypto.rb

@@ -18,7 +18,9 @@ module Mint
       @crypto_currencies || CRYPTO_MUTEX.synchronize do
         @crypto_currencies ||= begin
           path = File.join(File.expand_path('../../data', __dir__), 'crypto-currencies.yaml')
-          YAML.load_file(path).map { |entry| Currency.new(**entry.transform_keys(&:to_sym)) }.freeze
+          YAML.safe_load_file(path, aliases: false)
+              .map { |entry| Currency.new(**entry.transform_keys(&:to_sym)) }
+              .freeze
         end
       end
     end

data/lib/minting/mint/registry/registry.rb

@@ -16,7 +16,7 @@ module Mint
 
     # Preload world currencies from YAML file during module load.
     path = File.join(File.expand_path('../../data', __dir__), 'world-currencies.yaml')
-    @world_currencies = YAML.load_file(path).to_h do |entry|
+    @world_currencies = YAML.safe_load_file(path, aliases: false).to_h do |entry|
       [entry['code'], Currency.new(**entry.transform_keys(&:to_sym))]
     end
     @currencies = @world_currencies.freeze.dup.freeze

data/lib/minting/money/clamp.rb

@@ -8,28 +8,20 @@ module Mint
     # Bounds may be:
     # - nil meaning no boundary
     # - same-currency {Money} or Range
-    # - Numeric amount, or Range
-    #
-    # Numeric is interpreted as an amount in +self+'s currency, so the common
-    # pricing idiom +price.clamp(0, 100)+ reads as "0 to 100 in the same
-    # currency as +price+".
     #
     # When +self+ is already in range the receiver is returned (no new object
     # allocated). When out of range, the nearest bound is returned as a new
     # frozen {Money} in +self+'s currency.
     #
-    # @param min_or_range [Money, Numeric, Range, nil] lower bound (inclusive), or range
-    # @param max [Money, Numeric, nil] upper bound (inclusive)
+    # @param min_or_range [Money, Range, nil] lower bound (inclusive), or range
+    # @param max [Money, nil] upper bound (inclusive)
     # @return [Money] +self+ if in range, otherwise the nearer bound
-    # @raise [ArgumentError] if +min+ or +max+ is not a Money, Numeric or nil; if
+    # @raise [ArgumentError] if +min+ or +max+ is not a Money or nil; if
     #   a Money operand has a different currency; if +min+ > +max+;
     #   if min is a Range, and max is not nil
     #
     # @example In range
-    #   Money.from(5, 'USD').clamp(0, 10) #=> [USD 5.00]  (returns self)
-    #
-    # @example Out of range, with Numeric bounds
-    #   Money.from(50, 'USD').clamp(0, 10) #=> [USD 10.00]
+    #   Money.from(5, 'USD').clamp(Money.from(0, 'USD'), Money.from(10, 'USD')) #=> [USD 5.00]  (returns self)
     #
     # @example Out of range, with Money bounds
     #   loss  = Money.from(-5, 'USD')
@@ -37,8 +29,6 @@ module Mint
     #   ceil  = Money.from(10, 'USD')
     #   loss.clamp(floor, ceil) #=> [USD 0.00]
     #
-    # @example Subunit-0 currency (JPY)
-    #   Money.from(500, 'JPY').clamp(0, 100) #=> [JPY 100]
     def clamp(min_or_range, max = nil)
       if min_or_range.is_a?(Range)
         raise(ArgumentError, "Either amount range alone or two amounts accepted: #{max}") if max
@@ -56,10 +46,10 @@ module Mint
     # @private
     def normalize_boundary(boundary)
       case boundary
-      in NilClass | Numeric                then boundary
+      in NilClass                          then boundary
       in Money if same_currency?(boundary) then boundary.amount
       in Money                             then raise ArgumentError, "Boundary currency must be: #{currency_code}"
-      else                                 raise ArgumentError, "Boundary must be Numeric or Money #{boundary}"
+      else                                 raise ArgumentError, "Boundary must be Money or nil: #{boundary}"
       end
     end
   end

data/lib/minting/money/constructors.rb

@@ -44,7 +44,7 @@ module Mint
     #
     # @param subunits [Integer] the amount expressed in the currency's
     #   smallest unit (e.g. cents). Must be an Integer to preserve exactness.
-    # @param currency [String, Symbol, Currency] the currency identifier
+    # @param currency [String, Currency] the currency identifier
     # @return [Money] the resulting Money instance
     # @raise [ArgumentError] if +subunits+ is not an Integer
     # @raise [Mint::UnknownCurrency] if +currency+ is not registered

data/lib/minting/money/conversion.rb

@@ -12,7 +12,7 @@ module Mint
     # @return [BigDecimal] the decimal representation of the money amount
     # @example
     #   Money.from(9.99, 'USD').to_d  #=> 0.999e1
-    def to_d = amount.to_d 0
+    def to_d = BigDecimal(amount, 0)
 
     # Converts the monetary amount to a standard float.
     # Note: Using float conversion loses precision guarantees.

data/lib/minting/money/format/formatter.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'monitor'
+
 module Mint
   class Money
     # Compiles and caches formatter lambdas for a fixed combination of format
@@ -12,9 +14,22 @@ module Mint
     class Formatter
       extend FormatterValidator
 
-      def self.cache = @cache ||= {}
+      # Keep enough compiled configurations for typical application presets and
+      # locales without retaining every caller-provided template indefinitely.
+      CACHE_LIMIT = 256
+      CACHE_MUTEX = Monitor.new
+
+      private_constant :CACHE_MUTEX
 
-      # Returns a cached {Formatter} for the given configuration.
+      @cache = {}.freeze
+
+      class << self
+        attr_reader :cache
+      end
+
+      # Returns a cached {Formatter} for the given configuration. The cache is
+      # thread-safe and bounded by {CACHE_LIMIT}; once full, new configurations
+      # are compiled without being retained.
       # @param format [Hash{Symbol => String}] per-sign templates
       # @param decimal [String] decimal separator
       # @param thousand [String, false] thousands delimiter (+false+ disables)
@@ -23,10 +38,17 @@ module Mint
         formatter = cache[key]
         return formatter if formatter
 
-        validate_format!(format)
-        validate_separators!(decimal:, thousand:)
+        CACHE_MUTEX.synchronize do
+          formatter = cache[key]
+          return formatter if formatter
+
+          validate_format!(format)
+          validate_separators!(decimal:, thousand:)
 
-        cache[key] = new(format, decimal, thousand)
+          formatter = new(format, decimal, thousand)
+          @cache = cache.merge(key => formatter).freeze unless cache.size >= CACHE_LIMIT
+          formatter
+        end
       end
 
       def initialize(format, decimal, thousand)

data/lib/minting/money/format/to_s.rb

@@ -30,13 +30,14 @@ module Mint
       return format unless Mint.locale_backend.nil?
 
       subunit = currency.subunit
-      major = integral.to_s
+      sign = amount.negative? ? '-' : ''
+      major = integral.abs.to_s
       major.gsub!(THOUSAND_RE, '\1,') if amount.abs >= 1000
       if subunit > 0
         minor = fractional.abs.to_s.rjust(subunit, '0')
-        "#{currency.symbol}#{major}.#{minor}"
+        "#{currency.symbol}#{sign}#{major}.#{minor}"
       else
-        "#{currency.symbol}#{major}"
+        "#{currency.symbol}#{sign}#{major}"
       end
     end
   end

data/lib/minting/money/parse.rb

@@ -8,7 +8,8 @@ module Mint
     # Returns +nil+ when the input is invalid or currency cannot be determined.
     #
     # @param input [String] Amount input, optionally including a currency symbol or code
-    # @param currency [String, Symbol, Currency, nil] ISO code when not present in +input+
+    # @param currency [String, Currency, nil] default currency when none is present in +input+
+    #   An embedded currency code or symbol takes precedence over this argument.
     # @return [Money, nil]
     #
     # @example With explicit currency
@@ -27,17 +28,18 @@ module Mint
       currency = parse_currency(input, currency)
       return nil unless currency
 
-      amount = parse_amount(input)
+      amount = parse_amount(input, currency)
       return nil unless amount
 
       amount = currency.normalize_amount(amount)
-      new(amount, currency)
+      amount.zero? ? currency.zero : new(amount, currency)
     end
 
     # Like {.parse} but raises on failure.
     #
     # @param input [String] Amount input, optionally including a currency symbol or code
-    # @param currency [String, Symbol, Currency, nil] ISO code when not present in +input+
+    # @param currency [String, Currency, nil] default currency when none is present in +input+
+    #   An embedded currency code or symbol takes precedence over this argument.
     # @return [Money]
     # @raise [ArgumentError] when +input+ is invalid or currency cannot be determined
     #
@@ -53,21 +55,28 @@ module Mint
       currency = parse_currency(input, currency)
       raise ArgumentError, "Currency [#{currency}] not found" unless currency
 
-      amount = parse_amount(input)
+      amount = parse_amount(input, currency)
       raise ArgumentError, "Could not parse [#{input}]" unless amount
 
       amount = currency.normalize_amount(amount)
-      new(amount, currency)
+      amount.zero? ? currency.zero : new(amount, currency)
     end
 
     class << self
       private
 
-      # Extracts a numeric value from input that should only contain an amount.
-      def parse_amount(input)
+      # Extracts one valid numeric value, allowing surrounding currency markers
+      # and uppercase annotation words (for example, "MAX 10.00 USD").
+      def parse_amount(input, currency)
         accounting_negative = input.start_with?('(') && input.end_with?(')')
+        return nil if (input.include?('(') || input.include?(')')) && !accounting_negative
+
+        numeric_input = accounting_negative ? input[1...-1] : input
+        numeric_input = remove_currency_markers(numeric_input, currency)
+        numeric_input = numeric_input.gsub(/\b[A-Z_]+\b/, ' ').delete('[]').strip
+        numeric_input.sub!(/\A([+-])\s+/, '\\1')
+        return nil unless numeric_input.match?(/\A[+-]?\d[\d.,]*\z/)
 
-        numeric_input = input.gsub(/[^\d.,-]/, '')
         numeric = parse_separators(numeric_input)
         return nil unless numeric
 
@@ -75,6 +84,11 @@ module Mint
         accounting_negative ? -amount : amount
       end
 
+      def remove_currency_markers(input, currency)
+        markers = [currency.symbol, currency.disambiguate_symbol].compact.uniq
+        markers.reduce(input) { |result, marker| result.gsub(marker, ' ') }
+      end
+
       # Extracts currency from a string by matching ISO code or symbol.
       #
       # Scans all uppercase words and returns the first registered code, falling
@@ -95,6 +109,7 @@ module Mint
       # Converts locale-specific decimal/thousand separators into a plain decimal string.
       def parse_separators(numeric)
         return nil unless numeric.match?(/\d/)
+        return nil unless valid_numeric_syntax?(numeric)
 
         case classify_separators(numeric)
         when :decimal_period   then numeric
@@ -122,6 +137,16 @@ module Mint
         else                                 :thousands
         end
       end
+
+      def valid_numeric_syntax?(numeric)
+        unsigned = numeric.delete_prefix('-').delete_prefix('+')
+        unsigned.match?(/\A\d+\z/) ||
+          unsigned.match?(/\A\d+[.,]\d+\z/) ||
+          unsigned.match?(/\A\d+(?:,\d{3})+\.\d+\z/) ||
+          unsigned.match?(/\A\d+(?:\.\d{3})+,\d+\z/) ||
+          unsigned.match?(/\A\d+(?:,\d{3})+\z/) ||
+          unsigned.match?(/\A\d+(?:\.\d{3})+\z/)
+      end
     end
   end
 end

data/lib/minting/version.rb

@@ -3,5 +3,5 @@
 # Root namespace for the Minting library.
 module Minting
   # Current version of the Minting gem.
-  VERSION = '2.1.0'
+  VERSION = '2.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: minting
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Gilson Ferraz
@@ -36,6 +36,7 @@ files:
 - bin/check-currencies
 - bin/console
 - bin/setup
+- doc/agents/AGENTS.md
 - doc/agents/api_review-2026-06-15.md
 - doc/agents/copilot-instructions.md
 - doc/agents/expired/AGENTS.md
@@ -43,6 +44,8 @@ files:
 - doc/agents/expired/gemini_gem_evaluation.md
 - doc/agents/expired/recommendations.md
 - doc/agents/expired/rubocop-issues.md
+- doc/api_review-2026-08-13.md
+- doc/security-report.md
 - lib/minting.rb
 - lib/minting/aliases.rb
 - lib/minting/currency/currency.rb
@@ -104,7 +107,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.17
+rubygems_version: 4.0.18
 specification_version: 4
 summary: Library to manipulate currency values
 test_files: []