timeprice 0.1.2 → 0.3.0

data/lib/timeprice/cli.rb

@@ -3,6 +3,10 @@
 require "thor"
 require "json"
 require_relative "../timeprice"
+require_relative "cli/presenters/inflation"
+require_relative "cli/presenters/exchange"
+require_relative "cli/presenters/compare"
+require_relative "cli/presenters/sources"
 
 module Timeprice
   class CLI < Thor
@@ -16,8 +20,59 @@ module Timeprice
 
     class_option :json, type: :boolean, default: false, desc: "Output result as JSON"
 
+    # Return false so Thor::Error propagates to our wrapper in `start`, where
+    # we prettify the message and add a `See: timeprice help COMMAND` hint.
     def self.exit_on_failure?
-      true
+      false
+    end
+
+    KNOWN_COMMANDS = %w[inflation fx compare sources version].freeze
+
+    # Top-level help lists command names + descriptions only — matching git,
+    # gh, cargo. Arg signatures live in per-command help (`timeprice help fx`).
+    HELP_ROWS = [
+      ["inflation", "Inflation-adjust an amount between two dates"],
+      ["fx",        "Convert an amount between currencies on a date"],
+      ["compare",   "Combine FX + inflation across (year, currency) points"],
+      ["sources",   "List bundled data sources and coverage"],
+      ["version",   "Print the installed timeprice version"],
+    ].freeze
+
+    # Pass debug: true so Thor re-raises Thor::Error (including option-parse
+    # failures) instead of printing its own message and silently continuing
+    # when exit_on_failure? is false. We catch and format ourselves.
+    def self.start(given_args = ARGV, config = {})
+      super(given_args, config.merge(debug: true))
+    rescue Thor::Error => e
+      warn "Error: #{prettify_thor_message(e.message)}"
+      cmd = given_args.first
+      warn "  See: timeprice help #{cmd}" if KNOWN_COMMANDS.include?(cmd)
+      exit 1
+    end
+
+    def self.prettify_thor_message(msg)
+      msg
+        .sub(/\ANo value provided for required options /, "missing required options: ")
+        .gsub("'", "")
+    end
+
+    # Thor's API dictates the positional boolean signature — keyword arg
+    # would break the override.
+    def self.help(shell, subcommand = false) # rubocop:disable Style/OptionalBooleanParameter
+      return super if subcommand
+
+      shell.say "timeprice — offline historical inflation & FX for Ruby"
+      shell.say ""
+      shell.say "Commands:"
+      width = HELP_ROWS.map { |usage, _| usage.length }.max
+      HELP_ROWS.each do |usage, desc|
+        shell.say format("  %-#{width}s  %s", usage, desc)
+      end
+      shell.say ""
+      shell.say "Global options:"
+      shell.say "  --json   Output result as JSON"
+      shell.say ""
+      shell.say "Run `timeprice help COMMAND` for usage and options."
     end
 
     desc "inflation AMOUNT", "Inflation-adjust an amount between two dates"
@@ -27,12 +82,12 @@ module Timeprice
     def inflation(amount)
       with_error_handling do
         result = Timeprice.inflation(
-          amount: Float(amount),
+          amount: parse_amount(amount),
           from: options[:from],
           to: options[:to],
           country: options[:country]
         )
-        emit_inflation(result)
+        render Presenters::Inflation.new(result)
       end
     end
 
@@ -41,12 +96,12 @@ module Timeprice
     def fx(amount, from_currency, to_currency)
       with_error_handling do
         result = Timeprice.exchange(
-          amount: Float(amount),
+          amount: parse_amount(amount),
           from: from_currency,
           to: to_currency,
           date: options[:date]
         )
-        emit_exchange(result)
+        render Presenters::Exchange.new(result)
       end
     end
 
@@ -58,30 +113,19 @@ module Timeprice
         from_tuple = parse_compare_token(options[:from], label: "--from")
         to_tuple   = parse_compare_token(options[:to],   label: "--to")
         result = Timeprice.compare(
-          amount: Float(amount),
+          amount: parse_amount(amount),
           from: from_tuple,
           to: to_tuple
         )
-        emit_compare(result)
+        render Presenters::Compare.new(result)
       end
     end
 
     desc "sources", "List bundled data sources and coverage"
+    method_option :verbose, type: :boolean, default: false, aliases: "-v",
+                            desc: "Include license URLs and full attribution"
     def sources
-      list = Timeprice::Sources.list
-      if options[:json]
-        say JSON.generate(list)
-      else
-        list.each do |s|
-          say s[:name].to_s
-          say "  id:           #{s[:id]}"
-          say "  license:      #{s[:license]}"
-          say "  license_url:  #{s[:license_url]}"
-          say "  attribution:  #{s[:attribution]}"
-          say "  coverage:     #{s[:coverage]}"
-          say ""
-        end
-      end
+      render Presenters::Sources.new(Timeprice::Sources.list, verbose: options[:verbose])
     end
 
     desc "version", "Print the installed timeprice version"
@@ -94,19 +138,27 @@ module Timeprice
     end
 
     no_commands do
-      # Currencies with no minor unit — render whole numbers, no decimals.
-      ZERO_DECIMAL_CURRENCIES = %w[JPY VND].freeze
+      def render(presenter)
+        if options[:json]
+          say JSON.generate(presenter.json_hash)
+        else
+          presenter.text_lines.each { |line| say line }
+        end
+      end
 
       def with_error_handling
         yield
-      rescue Timeprice::Error => e
-        warn "Error: #{e.message}"
-        exit 1
-      rescue ArgumentError => e
+      rescue Timeprice::Error, ArgumentError => e
         warn "Error: #{e.message}"
         exit 1
       end
 
+      def parse_amount(raw)
+        Float(raw)
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "AMOUNT must be a number, got #{raw.inspect}"
+      end
+
       def parse_compare_token(token, label:)
         raise ArgumentError, "#{label} is required" if token.nil? || token.strip.empty?
 
@@ -115,100 +167,13 @@ module Timeprice
           raise ArgumentError,
                 "#{label} must be \"YEAR CURRENCY\" or \"CURRENCY YEAR\", got #{token.inspect}"
         end
-        year = parts.find { |p| p.match?(/\A\d{4}\z/) }
-        currency = parts.find { |p| p.match?(/\A[A-Za-z]{3}\z/) }
-        if year.nil? || currency.nil?
-          raise ArgumentError,
-                "#{label} must contain a 4-digit year and a 3-letter currency code, got #{token.inspect}"
-        end
-        [currency.upcase, year]
-      end
-
-      def fmt_money(amount, currency)
-        decimals = ZERO_DECIMAL_CURRENCIES.include?(currency.to_s.upcase) ? 0 : 2
-        format("%.#{decimals}f", amount)
-      end
 
-      def fmt_rate(rate)
-        abs = rate.to_f.abs
-        decimals = if abs >= 1000 then 0
-                   elsif abs >= 100 then 2
-                   elsif abs >= 10  then 3
-                   else 4
-                   end
-        format("%.#{decimals}f", rate)
-      end
-
-      # Granularity is loud noise on the happy path. Only surface it when the
-      # answer actually used annual data — that's where users want a heads-up.
-      def granularity_suffix(granularity)
-        return "" if granularity == :monthly
-
-        " (granularity: #{granularity})"
-      end
-
-      def emit_inflation(result)
-        if options[:json]
-          say JSON.generate(result.to_h)
-        else
-          ccy = result.country_currency_label
-          say format(
-            "%s %s in %s is %s %s in %s [%s]%s",
-            fmt_money(result.original_amount, ccy), ccy, result.from,
-            fmt_money(result.amount, ccy), ccy, result.to,
-            result.country, granularity_suffix(result.granularity)
-          )
-        end
-      end
-
-      def emit_exchange(result)
-        if options[:json]
-          say JSON.generate(result.to_h)
-        else
-          line = format(
-            "%s %s on %s = %s %s (rate: %s)",
-            fmt_money(result.original_amount, result.from), result.from, result.date,
-            fmt_money(result.amount, result.to), result.to, fmt_rate(result.rate)
-          )
-          if result.effective_date && result.effective_date != result.date
-            line += " [effective: #{result.effective_date}, fallback]"
-          end
-          say line
-        end
-      end
+        Point.coerce(parts)
+      rescue ArgumentError => e
+        raise if e.message.start_with?(label)
 
-      def emit_compare(result)
-        if options[:json]
-          say JSON.generate(result.to_h)
-        else
-          say format(
-            "%s %s in %s -> %s %s in %s",
-            fmt_money(result.original_amount, result.from_currency), result.from_currency, result.from_date,
-            fmt_money(result.amount, result.to_currency), result.to_currency, result.to_date
-          )
-          say format(
-            "  steps: %s %s -> %s %s (fx %s on %s), then inflate in %s x%.4f%s",
-            fmt_money(result.original_amount, result.from_currency), result.from_currency,
-            fmt_money(result.converted_amount, result.to_currency), result.to_currency,
-            fmt_rate(result.fx_rate), result.from_date,
-            result.country, result.cpi_ratio, granularity_suffix(result.granularity)
-          )
-        end
+        raise ArgumentError, "#{label}: #{e.message}"
       end
     end
   end
 end
-
-# Tiny shim so we can include currency context in the inflation line without
-# bloating the value object — the result doesn't carry currency, only country.
-module Timeprice
-  class InflationResult
-    COUNTRY_TO_CURRENCY = {
-      "US" => "USD", "UK" => "GBP", "EU" => "EUR", "JP" => "JPY", "VN" => "VND"
-    }.freeze
-
-    def country_currency_label
-      COUNTRY_TO_CURRENCY[country.to_s.upcase] || country.to_s.upcase
-    end
-  end
-end

data/lib/timeprice/compare.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "errors"
+require_relative "supported"
+require_relative "point"
 require_relative "inflation"
 require_relative "exchange"
 
@@ -26,37 +28,25 @@ module Timeprice
   # If a future refactor flips the order, the regression test in
   # spec/timeprice/compare_spec.rb will fail.
   module Compare
-    # Map ISO currency → CPI country code.
-    CURRENCY_TO_COUNTRY = {
-      "USD" => "US",
-      "GBP" => "UK",
-      "EUR" => "EU",
-      "JPY" => "JP",
-      "VND" => "VN",
-    }.freeze
-
     module_function
 
-    # amount: Numeric
-    # from:   [currency, date_or_year] e.g. ["USD", "2010"] or ["USD", "2010-06"]
-    # to:     [currency, date_or_year]
+    # Compare an amount across two (currency, date) points.
+    #
+    # @param amount [Numeric]
+    # @param from   [Timeprice::Point, Array(String, String)] source point;
+    #   accepts a {Point} or a 2-tuple like `["USD", "2010"]` or `["USD", "2010-06"]`
+    # @param to     [Timeprice::Point, Array(String, String)] destination point
+    # @return [CompareResult]
+    # @raise [UnsupportedCurrency] if either currency is not in {Supported::CURRENCIES}
     def run(amount:, from:, to:)
-      from_currency, from_date = from
-      to_currency,   to_date   = to
-      from_currency = from_currency.to_s.upcase
-      to_currency   = to_currency.to_s.upcase
-
-      to_country = CURRENCY_TO_COUNTRY[to_currency] ||
-                   (raise UnsupportedCurrency, to_currency)
-      CURRENCY_TO_COUNTRY[from_currency] || (raise UnsupportedCurrency, from_currency)
+      from_point, to_point, to_country = resolve_points(from, to)
 
       # Step 1: convert at source date into destination currency.
-      fx_date = normalize_fx_date(from_date)
       fx_result = Exchange.convert(
         amount: amount,
-        from: from_currency,
-        to: to_currency,
-        date: fx_date
+        from: from_point.currency,
+        to: to_point.currency,
+        date: from_point.fx_anchor_date
       )
       converted = fx_result.amount
 
@@ -64,18 +54,18 @@ module Timeprice
       # destination date using destination-country CPI.
       infl = Inflation.adjust(
         amount: converted,
-        from: from_date.to_s,
-        to: to_date.to_s,
+        from: from_point.date.to_s,
+        to: to_point.date.to_s,
         country: to_country
       )
 
       CompareResult.new(
         amount: infl.amount,
         original_amount: amount.to_f,
-        from_currency: from_currency,
-        from_date: from_date.to_s,
-        to_currency: to_currency,
-        to_date: to_date.to_s,
+        from_currency: from_point.currency,
+        from_date: from_point.date.to_s,
+        to_currency: to_point.currency,
+        to_date: to_point.date.to_s,
         country: to_country,
         fx_rate: fx_result.rate,
         cpi_ratio: infl.to_index.to_f / infl.from_index,
@@ -84,16 +74,16 @@ module Timeprice
       )
     end
 
-    # If the user gave a year like "2010", anchor FX to mid-year (2010-06-30).
-    # If they gave "YYYY-MM", anchor to the 15th. Full dates pass through.
-    def normalize_fx_date(date)
-      s = date.to_s
-      case s
-      when /\A\d{4}\z/ then "#{s}-06-30"
-      when /\A\d{4}-\d{2}\z/ then "#{s}-15"
-      when /\A\d{4}-\d{2}-\d{2}\z/ then s
-      else raise ArgumentError, "Invalid date for compare: #{date.inspect}"
-      end
+    # Coerce both points and resolve to_country.
+    def resolve_points(from, to)
+      from_point = Point.coerce(from)
+      to_point   = Point.coerce(to)
+      raise UnsupportedCurrency, from_point.currency unless Supported.country_for_currency(from_point.currency)
+
+      to_country = Supported.country_for_currency(to_point.currency)
+      raise UnsupportedCurrency, to_point.currency unless to_country
+
+      [from_point, to_point, to_country]
     end
   end
 end

data/lib/timeprice/cpi_lookup.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Timeprice
+  # CpiPoint pairs a CPI index value with the granularity of how it was
+  # resolved (monthly, annual, or annual derived by averaging 12 months).
+  CpiPoint = Data.define(:value, :granularity)
+
+  # Resolves CPI keys ("YYYY" or "YYYY-MM") to a CpiPoint against a single
+  # country's parsed CPI data hash. Knowing the JSON shape ("monthly" /
+  # "annual" string keys) is isolated here — Inflation just asks for points.
+  class CpiLookup
+    def initialize(data)
+      @data = data
+      @monthly = data["monthly"] || {}
+      @annual  = data["annual"]  || {}
+    end
+
+    # @param key [String] "YYYY" or "YYYY-MM"
+    # @return [CpiPoint]
+    # @raise [DataNotFound] if no CPI value covers `key`
+    # @raise [ArgumentError] on malformed `key`
+    def at(key)
+      key = key.to_s
+      case key
+      when /\A\d{4}-\d{2}\z/ then monthly_or_annual_fallback(key)
+      when /\A\d{4}\z/       then annual_or_monthly_average(key)
+      else raise ArgumentError, "Invalid date format: #{key.inspect} (use YYYY or YYYY-MM)"
+      end
+    end
+
+    private
+
+    def monthly_or_annual_fallback(month_key)
+      return CpiPoint.new(value: @monthly[month_key], granularity: :monthly) if @monthly.key?(month_key)
+
+      year = month_key[0, 4]
+      raise DataNotFound, missing_message(month_key) unless @annual.key?(year)
+
+      CpiPoint.new(value: @annual[year], granularity: :annual)
+    end
+
+    def annual_or_monthly_average(year)
+      return CpiPoint.new(value: @annual[year], granularity: :annual) if @annual.key?(year)
+
+      months = @monthly.select { |k, _| k.start_with?("#{year}-") }
+      raise DataNotFound, missing_message(year) if months.empty?
+
+      CpiPoint.new(value: months.values.sum.to_f / months.size, granularity: :annual_from_monthly_avg)
+    end
+
+    def missing_message(key)
+      country = @data["country"]
+      ranges = []
+      ranges << "monthly #{@monthly.keys.min}..#{@monthly.keys.max}" if @monthly.any?
+      ranges << "annual #{@annual.keys.min}..#{@annual.keys.max}" if @annual.any?
+      hint = ranges.empty? ? "" : " (supported: #{ranges.join(", ")})"
+      "No CPI data for #{key.inspect} in #{country}#{hint}"
+    end
+  end
+end

data/lib/timeprice/data_loader.rb

@@ -2,34 +2,49 @@
 
 require "json"
 require_relative "errors"
+require_relative "supported"
 
 module Timeprice
+  # Loads and caches the bundled JSON data files. Override the search root
+  # by setting `TIMEPRICE_DATA_ROOT` in the environment or assigning
+  # {DataLoader.data_root=}.
   module DataLoader
     SUPPORTED_SCHEMA_VERSION = 1
 
     DEFAULT_DATA_ROOT = File.expand_path("../../data", __dir__)
 
     class << self
+      # @return [String] absolute path to the directory containing `cpi/` and `fx/`
       def data_root
         ENV["TIMEPRICE_DATA_ROOT"] || @data_root || DEFAULT_DATA_ROOT
       end
 
+      # Override the data root and clear caches. Mostly useful in tests.
+      # @param path [String]
+      # @return [void]
       def data_root=(path)
         @data_root = path
         clear_cache!
       end
 
+      # Drop in-memory caches of parsed data files.
+      # @return [void]
       def clear_cache!
         @cpi_cache = {}
         @fx_cache = {}
       end
 
+      # Load the CPI series for a supported country.
+      # @param country [String]
+      # @return [Hash] parsed JSON with "monthly" / "annual" / metadata keys
+      # @raise [UnsupportedCountry] if `country` is not in {Supported::COUNTRIES}
+      # @raise [DataNotFound]       if the file is missing
+      # @raise [UnsupportedSchemaVersion] if the file uses a future schema
       def load_cpi(country)
-        @cpi_cache ||= {}
         key = country.to_s.downcase
         code = country.to_s.upcase
-        @cpi_cache[[data_root, key]] ||= begin
-          raise UnsupportedCountry, code unless SUPPORTED_COUNTRIES.include?(code)
+        cpi_cache[[data_root, key]] ||= begin
+          raise UnsupportedCountry, code unless Supported::COUNTRIES.include?(code)
 
           path = File.join(data_root, "cpi", "#{key}.json")
           unless File.exist?(path)
@@ -41,10 +56,13 @@ module Timeprice
         end
       end
 
+      # Load the FX rates for a year.
+      # @param year [Integer, String]
+      # @return [Hash] parsed JSON with a "rates" map of date → currency → Float
+      # @raise [DataNotFound] if the per-year file is missing
       def load_fx_year(year)
-        @fx_cache ||= {}
         key = year.to_i
-        @fx_cache[[data_root, key]] ||= begin
+        fx_cache[[data_root, key]] ||= begin
           path = File.join(data_root, "fx", "usd", "#{key}.json")
           raise DataNotFound, "No FX data for year #{key}" unless File.exist?(path)
 
@@ -54,6 +72,14 @@ module Timeprice
 
       private
 
+      def cpi_cache
+        @cpi_cache ||= {}
+      end
+
+      def fx_cache
+        @fx_cache ||= {}
+      end
+
       def parse_with_schema(path)
         data = JSON.parse(File.read(path))
         version = data["schema_version"]

data/lib/timeprice/errors.rb

@@ -1,29 +1,33 @@
 # frozen_string_literal: true
 
+require_relative "supported"
+
 module Timeprice
+  # Base class for every error this library raises. Catch `Timeprice::Error`
+  # to handle anything the gem can throw at you.
   class Error < StandardError; end
 
-  SUPPORTED_COUNTRIES = %w[US UK EU JP VN].freeze
-  SUPPORTED_CURRENCIES = %w[USD GBP EUR JPY VND].freeze
-
+  # Raised when a country code is not in {Supported::COUNTRIES}.
   class UnsupportedCountry < Error
     attr_reader :country
 
     def initialize(country)
       @country = country
-      super("Unsupported country: #{country.inspect} (supported: #{SUPPORTED_COUNTRIES.join(", ")})")
+      super("Unsupported country: #{country.inspect} (supported: #{Supported::COUNTRIES.join(", ")})")
     end
   end
 
+  # Raised when a currency code is not in {Supported::CURRENCIES}.
   class UnsupportedCurrency < Error
     attr_reader :currency
 
     def initialize(currency)
       @currency = currency
-      super("Unsupported currency: #{currency.inspect} (supported: #{SUPPORTED_CURRENCIES.join(", ")})")
+      super("Unsupported currency: #{currency.inspect} (supported: #{Supported::CURRENCIES.join(", ")})")
     end
   end
 
+  # Raised when a requested date falls outside the bundled data range.
   class DateOutOfRange < Error
     attr_reader :date, :range
 
@@ -34,12 +38,15 @@ module Timeprice
     end
   end
 
+  # Raised when a CPI or FX lookup has no usable data point.
   class DataNotFound < Error
     def initialize(message = "Data not found")
       super
     end
   end
 
+  # Raised when a bundled data file declares a schema_version this gem
+  # doesn't know how to parse (forward-compat guard).
   class UnsupportedSchemaVersion < Error
     attr_reader :version, :path
 

data/lib/timeprice/exchange.rb

@@ -3,12 +3,17 @@
 require "date"
 require_relative "errors"
 require_relative "data_loader"
+require_relative "supported"
 
 module Timeprice
   ExchangeResult = Data.define(
     :amount, :original_amount, :from, :to, :date, :effective_date, :rate
   )
 
+  # Historical FX conversion using bundled per-year USD-base rate files.
+  # Handles identity (USD→USD), direct lookup, inverse, and triangulation
+  # through USD. Weekend/holiday dates fall back up to {MAX_FALLBACK_DAYS}
+  # days to the nearest prior trading day.
   module Exchange
     BASE = "USD"
     MAX_FALLBACK_DAYS = 7
@@ -16,12 +21,19 @@ module Timeprice
     module_function
 
     # Convert `amount` from currency `from` to currency `to` on `date`.
-    # date: "YYYY-MM-DD".
+    #
+    # @param amount [Numeric]
+    # @param from   [String] ISO 4217 source currency
+    # @param to     [String] ISO 4217 destination currency
+    # @param date   [String, Date] date as "YYYY-MM-DD" or a Date instance
+    # @return [ExchangeResult]
+    # @raise [UnsupportedCurrency] if `from` or `to` is not supported
+    # @raise [DataNotFound]        if no FX point exists within {MAX_FALLBACK_DAYS}
     def convert(amount:, from:, to:, date:)
       from = from.to_s.upcase
       to   = to.to_s.upcase
-      raise UnsupportedCurrency, from unless SUPPORTED_CURRENCIES.include?(from)
-      raise UnsupportedCurrency, to   unless SUPPORTED_CURRENCIES.include?(to)
+      raise UnsupportedCurrency, from unless Supported::CURRENCIES.include?(from)
+      raise UnsupportedCurrency, to   unless Supported::CURRENCIES.include?(to)
 
       d = parse_date(date)