timeprice 0.2.0 → 0.4.0

data/data/fx/usd/2025.json

@@ -1,5 +1,9 @@
 {
+  "schema_version": 2,
   "base": "USD",
+  "year": 2025,
+  "source": "Frankfurter (ECB) — daily reference rates",
+  "updated_at": "2026-05-11",
   "rates": {
     "2025-01-02": {
       "EUR": 0.9689,
@@ -1276,9 +1280,5 @@
       "GBP": 0.74264,
       "JPY": 156.67
     }
-  },
-  "schema_version": 1,
-  "source": "Frankfurter (ECB) — daily reference rates",
-  "updated_at": "2026-05-11",
-  "year": 2025
+  }
 }

data/data/fx/usd/2026.json

@@ -1,5 +1,9 @@
 {
+  "schema_version": 2,
   "base": "USD",
+  "year": 2026,
+  "source": "Frankfurter (ECB) — daily reference rates",
+  "updated_at": "2026-05-11",
   "rates": {
     "2026-01-02": {
       "EUR": 0.85317,
@@ -441,9 +445,5 @@
       "GBP": 0.73472,
       "JPY": 156.76
     }
-  },
-  "schema_version": 1,
-  "source": "Frankfurter (ECB) — daily reference rates",
-  "updated_at": "2026-05-11",
-  "year": 2026
+  }
 }

data/lib/timeprice/cli/formatting.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "../supported"
+
+module Timeprice
+  class CLI < Thor
+    # Number/currency formatting helpers shared by every CLI emitter.
+    # Lives as a mixin (rather than a free-standing module function set) so
+    # callers can use the helpers as plain methods inside `no_commands` blocks.
+    module Formatting
+      def fmt_money(amount, currency)
+        with_commas(format("%.#{Supported.decimals_for(currency)}f", amount))
+      end
+
+      # Two decimals once we're past the unit threshold; six decimals for
+      # sub-unit rates so tiny rates (e.g. 0.000045) still carry signal.
+      def fmt_rate(rate)
+        decimals = rate.to_f.abs >= 1 ? 2 : 6
+        with_commas(format("%.#{decimals}f", rate))
+      end
+
+      def round_money(amount, currency)
+        amount.to_f.round(Supported.decimals_for(currency))
+      end
+
+      def with_commas(num_str)
+        sign = num_str.start_with?("-") ? "-" : ""
+        whole, frac = num_str.sub(/\A-/, "").split(".", 2)
+        whole = whole.reverse.gsub(/(\d{3})(?=\d)/, '\1,').reverse
+        frac ? "#{sign}#{whole}.#{frac}" : "#{sign}#{whole}"
+      end
+    end
+  end
+end

data/lib/timeprice/cli/presenters/compare.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../formatting"
+require_relative "../../granularity"
+
+module Timeprice
+  class CLI < Thor
+    module Presenters
+      # Renders a CompareResult for the CLI in text and JSON formats.
+      class Compare
+        include Formatting
+
+        def initialize(result)
+          @result = result
+        end
+
+        def json_hash
+          @result.to_h.merge(
+            amount: round_money(@result.amount, @result.to_currency),
+            original_amount: round_money(@result.original_amount, @result.from_currency),
+            converted_amount: round_money(@result.converted_amount, @result.to_currency),
+            fx_rate: @result.fx_rate.to_f.round(6),
+            cpi_ratio: @result.cpi_ratio.to_f.round(6)
+          )
+        end
+
+        # Headline + left-to-right chain so the FX + CPI composition reads naturally.
+        def text_lines
+          final = "#{fmt_money(@result.amount, @result.to_currency)} #{@result.to_currency}"
+          original = "#{fmt_money(@result.original_amount, @result.from_currency)} #{@result.from_currency}"
+          converted = "#{fmt_money(@result.converted_amount, @result.to_currency)} #{@result.to_currency}"
+          step1 = "fx @ #{fmt_rate(@result.fx_rate)}"
+          step2 = "inflate x#{format("%.4f", @result.cpi_ratio)} #{@result.country}"
+          width = [step1.length, step2.length].max
+          [
+            "#{final}  in #{@result.to_date}",
+            "  #{original} (#{@result.from_date})",
+            format("    -> %-#{width}s -> %s (%s)", step1, converted, @result.from_date),
+            format("    -> %-#{width}s -> %s (%s, %s)", step2, final, @result.to_date,
+                   Granularity.humanize(@result.granularity)),
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/timeprice/cli/presenters/exchange.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../formatting"
+
+module Timeprice
+  class CLI < Thor
+    module Presenters
+      # Renders an ExchangeResult for the CLI in text and JSON formats.
+      class Exchange
+        include Formatting
+
+        def initialize(result)
+          @result = result
+        end
+
+        def json_hash
+          @result.to_h.merge(
+            amount: round_money(@result.amount, @result.to),
+            original_amount: round_money(@result.original_amount, @result.from),
+            rate: @result.rate.to_f.round(6)
+          )
+        end
+
+        def text_lines
+          [
+            "#{fmt_money(@result.amount, @result.to)} #{@result.to}  on #{@result.date}",
+            format("  %s %s -> %s %s",
+                   fmt_money(@result.original_amount, @result.from), @result.from,
+                   fmt_money(@result.amount, @result.to), @result.to),
+            "  #{rate_line}",
+          ]
+        end
+
+        private
+
+        def rate_line
+          line = "rate #{fmt_rate(@result.rate)}"
+          return line unless @result.effective_date && @result.effective_date != @result.date
+
+          "#{line} from #{@result.effective_date} (fallback)"
+        end
+      end
+    end
+  end
+end

data/lib/timeprice/cli/presenters/inflation.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "../formatting"
+require_relative "../../granularity"
+
+module Timeprice
+  class CLI < Thor
+    module Presenters
+      # Renders an InflationResult for the CLI in text and JSON formats.
+      class Inflation
+        include Formatting
+
+        def initialize(result)
+          @result = result
+          @ccy = result.country_currency_label
+        end
+
+        def json_hash
+          @result.to_h.merge(
+            amount: round_money(@result.amount, @ccy),
+            original_amount: round_money(@result.original_amount, @ccy)
+          )
+        end
+
+        def text_lines
+          [
+            "#{fmt_money(@result.amount, @ccy)} #{@ccy}  in #{@result.to}",
+            format("  %s %s (%s) -> %s %s (%s)",
+                   fmt_money(@result.original_amount, @ccy), @ccy, @result.from,
+                   fmt_money(@result.amount, @ccy), @ccy, @result.to),
+            "  #{@result.country} · #{Granularity.humanize(@result.granularity)} CPI",
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/timeprice/cli/presenters/sources.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Timeprice
+  class CLI < Thor
+    module Presenters
+      # Renders the sources list in compact-table, verbose, and JSON formats.
+      class Sources
+        MAX_SOURCE_NAME = 60
+
+        def initialize(list, verbose: false)
+          @list = list
+          @verbose = verbose
+        end
+
+        def json_hash
+          @list
+        end
+
+        def text_lines
+          @verbose ? verbose_lines : table_lines
+        end
+
+        private
+
+        def table_lines
+          rows = @list.map do |s|
+            [s[:id].to_s, short_source_name(s[:name]), s[:license].to_s, s[:coverage].to_s]
+          end
+          headers = %w[ID SOURCE LICENSE COVERAGE]
+          widths = headers.each_with_index.map { |h, i| [h.length, *rows.map { |r| r[i].length }].max }
+          fmt = "  %-#{widths[0]}s  %-#{widths[1]}s  %-#{widths[2]}s  %s"
+          [
+            format(fmt, *headers),
+            *rows.map { |r| format(fmt, *r) },
+            "",
+            "Run `timeprice sources --verbose` for license URLs and full attribution.",
+          ]
+        end
+
+        def verbose_lines
+          @list.flat_map do |s|
+            [
+              s[:name].to_s,
+              "  id:           #{s[:id]}",
+              "  license:      #{s[:license]}",
+              "  license_url:  #{s[:license_url]}",
+              "  attribution:  #{s[:attribution]}",
+              "  coverage:     #{s[:coverage]}",
+              "",
+            ]
+          end
+        end
+
+        # Cap the source-name column width. Truncation is last resort — the full
+        # name (with series code) is preserved in `--verbose` output.
+        def short_source_name(name)
+          s = name.to_s
+          return s if s.length <= MAX_SOURCE_NAME
+
+          "#{s[0, MAX_SOURCE_NAME - 1]}…"
+        end
+      end
+    end
+  end
+end

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,96 +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
-    def country_currency_label
-      Supported.currency_for_country(country) || country.to_s.upcase
-    end
-  end
-end

data/lib/timeprice/compare.rb

@@ -5,6 +5,7 @@ require_relative "supported"
 require_relative "point"
 require_relative "inflation"
 require_relative "exchange"
+require_relative "granularity"
 
 module Timeprice
   CompareResult = Data.define(
@@ -28,10 +29,6 @@ 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. Kept as a back-compat alias;
-    # the canonical map lives in {Supported::CURRENCY_TO_COUNTRY}.
-    CURRENCY_TO_COUNTRY = Supported::CURRENCY_TO_COUNTRY
-
     module_function
 
     # Compare an amount across two (currency, date) points.
@@ -43,15 +40,14 @@ module Timeprice
     # @return [CompareResult]
     # @raise [UnsupportedCurrency] if either currency is not in {Supported::CURRENCIES}
     def run(amount:, from:, to:)
-      from_currency, from_date, to_currency, to_date, to_country = resolve_points(from, to)
+      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
 
@@ -59,49 +55,36 @@ 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,
         converted_amount: converted,
-        granularity: infl.granularity
+        granularity: Granularity.merge(fx_result.granularity, infl.granularity)
       )
     end
 
-    # Coerce both points and resolve to_country. Returns a 5-element tuple.
+    # Coerce both points and resolve to_country.
     def resolve_points(from, to)
       from_point = Point.coerce(from)
       to_point   = Point.coerce(to)
-      from_currency = from_point.currency
-      to_currency   = to_point.currency
-      to_country = Supported.country_for_currency(to_currency) ||
-                   (raise UnsupportedCurrency, to_currency)
-      Supported.country_for_currency(from_currency) || (raise UnsupportedCurrency, from_currency)
+      raise UnsupportedCurrency, from_point.currency unless Supported.country_for_currency(from_point.currency)
 
-      [from_currency, from_point.date, to_currency, to_point.date, to_country]
-    end
+      to_country = Supported.country_for_currency(to_point.currency)
+      raise UnsupportedCurrency, to_point.currency unless to_country
 
-    # 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
+      [from_point, to_point, to_country]
     end
   end
 end