timeprice 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 160a9501bc1004df45cd71202f3ae07711068adade2118cfe4605a2e92d92f6f
-  data.tar.gz: 68ea05103245f2bb1fb02d701fd5db6e1bb814a2b47d20f6eb9011d94a57b269
+  metadata.gz: 3b400f9dc1652d4476d884f59a2721e4f07338e76c5cc7afab50896267e1123c
+  data.tar.gz: 1a894e2464aa1f1495ddaa24c284b819a8afc07309cd3080f7c8c70744959ef2
 SHA512:
-  metadata.gz: fdddfd9cbcf4cefad6ee73134eb8ef3e5ad5b863aa8d5a78fa789b8890cefec0690cf3c1022f1b596c2bdeaf6f9a8f1122d8ff6ef9adfb7dd393e0aa9346afb6
-  data.tar.gz: 4342d02e30f4058f6e7a98eedab2fd0fa54b14031f061bf4d17b093d02f6a1e5cd16ea1f994e7d868cc893fe29119bdae1a398724665f14502c9b135ee1396b0
+  metadata.gz: 1f2c0b9ae5a4f8de71bdfdfb28f911b676773d406f86149b0c12ad5fbeb002ad51e42d43ed9f21d41c6ddd1a5b2760c2df58796759f66e7b78ac0dc784cee971
+  data.tar.gz: 8dc9e2ff73ddf7d0126538794bb4612a8709881628b713a1e878fe8fba7eddd510597f5a4f0a07e8c9d3b63cc751880df9150db208616f7fc52306ae2474bd10

data/CHANGELOG.md

@@ -5,6 +5,55 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-05-11
+
+### Added
+- `Timeprice::CpiLookup` and `Timeprice::CpiPoint` (Data.define of value +
+  granularity). Owns all knowledge of the parsed CPI JSON shape so
+  `Inflation.adjust` is a 6-line orchestration.
+- `Timeprice::Sources::Coverage` — isolates runtime filesystem walking
+  (FX year scan, JSON.parse of rate files) from the attribution registry.
+- `Timeprice::Point#fx_anchor_date` — resolves a year / month / day `Point`
+  to the day-resolved string FX lookup needs (mid-year for `YYYY`,
+  mid-month for `YYYY-MM`).
+- `Timeprice::Supported.decimals_for(currency)` — single source of truth
+  for ISO 4217 minor-unit counts; non-CLI callers of `Timeprice.exchange`
+  can now format results consistently.
+- `Timeprice::CLI::Presenters::{Inflation, Exchange, Compare, Sources}` —
+  each presenter exposes `#text_lines` and `#json_hash`; the CLI dispatches
+  via a single `#render(presenter)` helper.
+
+### Changed
+- CLI output redesigned for readability: every `inflation`, `fx`, and `compare`
+  command now leads with the answer on line 1 (e.g. `3,530,921 VND  in 2024`),
+  followed by the calculation chain indented below. `head -1` extracts just
+  the headline. Numbers are comma-grouped; JSON output is rounded to currency
+  precision (no more `1861291.9999999998`).
+- `timeprice sources` now renders as an aligned `ID / SOURCE / LICENSE /
+  COVERAGE` table by default. Use `timeprice sources --verbose` (`-v`) for the
+  previous detailed view with license URLs and full attribution.
+- Top-level `timeprice help` rewritten — no more truncated descriptions; lists
+  command names + descriptions, matching the `git` / `gh` / `cargo` convention.
+- `Point.coerce` rewritten with pattern matching; the CLI's
+  `parse_compare_token` now delegates to it instead of re-implementing
+  the shape rules.
+- `Compare.resolve_points` uses explicit `raise … unless` guards instead of
+  `… || (raise …)` nil-pun.
+
+### Removed
+- Undocumented back-compat constants: `Timeprice::SUPPORTED_COUNTRIES`,
+  `Timeprice::SUPPORTED_CURRENCIES`, and `Timeprice::Compare::CURRENCY_TO_COUNTRY`.
+  Use `Supported::COUNTRIES`, `Supported::CURRENCIES`, and
+  `Supported::CURRENCY_TO_COUNTRY` directly.
+- `Lint/DuplicateBranch` RuboCop exclusion for `cli.rb` — the duplicate
+  was collapsed into a single `rescue Timeprice::Error, ArgumentError`.
+
+### Fixed
+- Friendlier error messages: `Error: AMOUNT must be a number, got "abc"`
+  instead of Ruby's raw `invalid value for Float(): "abc"`. Missing-options
+  errors now say `missing required options: --from, --to` with a `See:
+  timeprice help inflation` hint.
+
 ## [0.2.0] - 2026-05-11
 
 ### Added

data/README.md

@@ -32,16 +32,25 @@ Requires Ruby >= 3.2.
 
 ```bash
 $ timeprice inflation 100 --from 1990-01 --to 2024-01 --country US
-100.00 USD in 1990-01 is 242.09 USD in 2024-01 (US, granularity: monthly)
+242.09 USD  in 2024-01
+  100.00 USD (1990-01) -> 242.09 USD (2024-01)
+  US · monthly CPI
 
 $ timeprice fx 100 USD JPY --date 2010-06-15
-100.00 USD on 2010-06-15 = 9118.00 JPY (rate: 91.1800)
+9,118 JPY  on 2010-06-15
+  100.00 USD -> 9,118 JPY
+  rate 91.18
 
 $ timeprice compare 100 --from "2010 USD" --to "2024 VND"
-100.00 USD in 2010 -> 3530920.58 VND in 2024
-  steps: convert at 2010 (fx rate 18612.920000) -> 1861292.0000 VND, then inflate in VN (cpi ratio 1.897027, granularity: annual)
+3,530,921 VND  in 2024
+  100.00 USD (2010)
+    -> fx @ 18,612.92     -> 1,861,292 VND (2010)
+    -> inflate x1.8970 VN -> 3,530,921 VND (2024, annual)
 ```
 
+The first line of each result is the answer — pipe through `head -1` if a
+script only needs the headline figure.
+
 Every command supports `--json` for machine-readable output:
 
 ```bash

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,44 @@
+# frozen_string_literal: true
+
+require_relative "../formatting"
+
+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, @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,36 @@
+# frozen_string_literal: true
+
+require_relative "../formatting"
+
+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} · #{@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

@@ -28,10 +28,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 +39,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,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,
@@ -79,29 +74,16 @@ module Timeprice
       )
     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

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,6 +2,7 @@
 
 require "json"
 require_relative "errors"
+require_relative "supported"
 
 module Timeprice
   # Loads and caches the bundled JSON data files. Override the search root
@@ -40,11 +41,10 @@ module Timeprice
       # @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)
@@ -61,9 +61,8 @@ module Timeprice
       # @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)
 
@@ -73,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/exchange.rb

@@ -3,6 +3,7 @@
 require "date"
 require_relative "errors"
 require_relative "data_loader"
+require_relative "supported"
 
 module Timeprice
   ExchangeResult = Data.define(
@@ -31,8 +32,8 @@ module Timeprice
     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)
 

data/lib/timeprice/inflation.rb

@@ -2,6 +2,7 @@
 
 require_relative "errors"
 require_relative "data_loader"
+require_relative "cpi_lookup"
 
 module Timeprice
   # Value object returned by Inflation.adjust.
@@ -14,7 +15,15 @@ module Timeprice
   InflationResult = Data.define(
     :amount, :original_amount, :from, :to, :country,
     :from_index, :to_index, :granularity
-  )
+  ) do
+    # The country's primary currency (e.g. "USD" for "US"). Falls back to the
+    # uppercased country code if the country isn't in the supported map —
+    # callers can still render *some* unit rather than crashing.
+    def country_currency_label
+      require_relative "supported"
+      Supported.currency_for_country(country) || country.to_s.upcase
+    end
+  end
 
   # CPI-based inflation adjustment for the {Supported::COUNTRIES} list.
   module Inflation
@@ -32,20 +41,20 @@ module Timeprice
     # @raise [UnsupportedCountry] if `country` is not supported
     # @raise [DataNotFound]       if no CPI data covers the requested period
     def adjust(amount:, from:, to:, country:)
-      data = DataLoader.load_cpi(country)
-      from_index, from_gran = lookup_index(data, from)
-      to_index,   to_gran   = lookup_index(data, to)
+      lookup = CpiLookup.new(DataLoader.load_cpi(country))
+      from_point = lookup.at(from)
+      to_point   = lookup.at(to)
 
-      ratio = to_index.to_f / from_index
+      ratio = to_point.value.to_f / from_point.value
       InflationResult.new(
         amount: amount.to_f * ratio,
         original_amount: amount.to_f,
         from: from,
         to: to,
         country: country.to_s.upcase,
-        from_index: from_index,
-        to_index: to_index,
-        granularity: merge_granularity(from_gran, to_gran)
+        from_index: from_point.value,
+        to_index: to_point.value,
+        granularity: merge_granularity(from_point.granularity, to_point.granularity)
       )
     end
 
@@ -60,53 +69,6 @@ module Timeprice
       result.amount - 1.0
     end
 
-    # Returns [index_value, granularity_symbol]
-    def lookup_index(data, key)
-      key = key.to_s
-      monthly = data["monthly"] || {}
-      annual  = data["annual"]  || {}
-
-      case key
-      when /\A\d{4}-\d{2}\z/
-        if monthly.key?(key)
-          [monthly[key], :monthly]
-        else
-          year = key[0, 4]
-          raise DataNotFound, missing_cpi_message(key, data, monthly, annual) unless annual.key?(year)
-
-          [annual[year], :annual]
-
-        end
-      when /\A\d{4}\z/
-        if annual.key?(key)
-          [annual[key], :annual]
-        else
-          months = monthly.select { |k, _| k.start_with?("#{key}-") }
-          raise DataNotFound, missing_cpi_message(key, data, monthly, annual) if months.empty?
-
-          avg = months.values.sum.to_f / months.size
-          [avg, :annual_from_monthly_avg]
-        end
-      else
-        raise ArgumentError, "Invalid date format: #{key.inspect} (use YYYY or YYYY-MM)"
-      end
-    end
-
-    def missing_cpi_message(key, data, monthly, annual)
-      country = data["country"]
-      ranges = []
-      if monthly.any?
-        ks = monthly.keys.sort
-        ranges << "monthly #{ks.first}..#{ks.last}"
-      end
-      if annual.any?
-        ks = annual.keys.sort
-        ranges << "annual #{ks.first}..#{ks.last}"
-      end
-      hint = ranges.empty? ? "" : " (supported: #{ranges.join(", ")})"
-      "No CPI data for #{key.inspect} in #{country}#{hint}"
-    end
-
     # If either end fell back to annual_from_monthly_avg, propagate that label;
     # else if either is annual, propagate :annual; else :monthly.
     def merge_granularity(a, b)

data/lib/timeprice/point.rb

@@ -21,23 +21,42 @@ module Timeprice
     # @return [Point]
     # @raise [ArgumentError] if shape can't be recognised
     def self.coerce(input)
-      return input if input.is_a?(Point)
+      case input
+      in Point
+        input
+      in [_, _]
+        a, b = input.map(&:to_s)
+        currency = [a, b].find { |s| s.match?(/\A[A-Za-z]{3}\z/) }
+        date     = [a, b].find { |s| s.match?(/\A\d{4}(-\d{2}(-\d{2})?)?\z/) }
+        raise ArgumentError, malformed_pair_message(input) if currency.nil? || date.nil?
 
-      unless input.is_a?(Array) && input.size == 2
+        new(currency: currency.upcase, date: date)
+      else
         raise ArgumentError, "Expected Timeprice::Point or [currency, date] tuple, got #{input.inspect}"
       end
+    end
 
-      a, b = input.map(&:to_s)
-      currency = [a, b].find { |s| s.match?(/\A[A-Za-z]{3}\z/) }
-      date     = [a, b].find { |s| s.match?(/\A\d{4}(-\d{2}(-\d{2})?)?\z/) }
+    def self.malformed_pair_message(input)
+      "Could not detect currency + date in #{input.inspect} " \
+        "(expected a 3-letter currency and a YYYY[-MM[-DD]] date)"
+    end
 
-      if currency.nil? || date.nil?
-        raise ArgumentError,
-              "Could not detect currency + date in #{input.inspect} " \
-              "(expected a 3-letter currency and a YYYY[-MM[-DD]] date)"
+    # Resolve `date` to a full YYYY-MM-DD for FX lookup.
+    #
+    # Coarser grains anchor to a representative day:
+    #   - "YYYY"    → mid-year (YYYY-06-30)
+    #   - "YYYY-MM" → mid-month (YYYY-MM-15)
+    #   - "YYYY-MM-DD" → passes through
+    #
+    # @return [String]
+    # @raise [ArgumentError] if `date` doesn't match any supported shape
+    def fx_anchor_date
+      case date.to_s
+      when /\A\d{4}\z/         then "#{date}-06-30"
+      when /\A\d{4}-\d{2}\z/   then "#{date}-15"
+      when /\A\d{4}-\d{2}-\d{2}\z/ then date.to_s
+      else raise ArgumentError, "Invalid date for Point: #{date.inspect}"
       end
-
-      new(currency: currency.upcase, date: date)
     end
   end
 end

data/lib/timeprice/sources/coverage.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../data_loader"
+
+module Timeprice
+  module Sources
+    # Computes coverage strings for bundled data sources at runtime. All
+    # filesystem reads happen here so the Sources attribution registry stays
+    # a pure data table.
+    module Coverage
+      module_function
+
+      # @param src [Hash] one entry from Sources::ATTRIBUTIONS
+      # @return [String]
+      def for(src)
+        case src[:kind]
+        when "cpi" then cpi(src[:country])
+        when "fx"  then fx(src[:id])
+        else "n/a"
+        end
+      rescue StandardError => e
+        "(coverage unavailable: #{e.message})"
+      end
+
+      def cpi(country)
+        data = DataLoader.load_cpi(country)
+        monthly = (data["monthly"] || {}).keys.sort
+        annual  = (data["annual"]  || {}).keys.sort
+        parts = []
+        parts << "monthly #{monthly.first}..#{monthly.last} (#{monthly.size})" unless monthly.empty?
+        parts << "annual #{annual.first}..#{annual.last} (#{annual.size})" unless annual.empty?
+        parts.join(", ")
+      end
+
+      def fx(id)
+        years = fx_years
+        return "no data" if years.empty?
+
+        id == "fx_vnd" ? vnd_summary(years) : ecb_summary(years)
+      end
+
+      def fx_years
+        Dir[File.join(fx_root, "*.json")].map { |f| File.basename(f, ".json").to_i }.sort
+      end
+
+      def vnd_summary(years)
+        with_vnd = years.select { |y| year_has_currency?(y, %w[VND]) }
+        return "no VND data" if with_vnd.empty?
+
+        "USD↔VND #{with_vnd.first}..#{with_vnd.last}"
+      end
+
+      def ecb_summary(years)
+        ecb_years = years.select { |y| year_has_currency?(y, %w[EUR GBP JPY]) }
+        return "no ECB data" if ecb_years.empty?
+
+        "USD↔EUR/GBP/JPY daily #{ecb_years.first}..#{ecb_years.last}"
+      end
+
+      def year_has_currency?(year, codes)
+        rates = JSON.parse(File.read(File.join(fx_root, "#{year}.json")))["rates"]
+        rates.any? { |_, v| v.keys.intersect?(codes) }
+      end
+
+      def fx_root
+        File.join(DataLoader.data_root, "fx", "usd")
+      end
+    end
+  end
+end

data/lib/timeprice/sources.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "data_loader"
+require_relative "sources/coverage"
 
 module Timeprice
   # Enumerate bundled data sources with license/attribution and the actual
@@ -79,54 +79,7 @@ module Timeprice
     # :attribution, :coverage (string like "1990-01 to 2026-03 (monthly+annual)").
     # @return [Array<Hash>]
     def list
-      ATTRIBUTIONS.map { |s| s.merge(coverage: coverage_for(s)) }
-    end
-
-    def coverage_for(src)
-      case src[:kind]
-      when "cpi" then cpi_coverage(src[:country])
-      when "fx"  then fx_coverage(src[:id])
-      else "n/a"
-      end
-    rescue StandardError => e
-      "(coverage unavailable: #{e.message})"
-    end
-
-    def cpi_coverage(country)
-      data = DataLoader.load_cpi(country)
-      monthly = (data["monthly"] || {}).keys.sort
-      annual  = (data["annual"]  || {}).keys.sort
-      parts = []
-      parts << "monthly #{monthly.first}..#{monthly.last} (#{monthly.size})" unless monthly.empty?
-      parts << "annual #{annual.first}..#{annual.last} (#{annual.size})" unless annual.empty?
-      parts.join(", ")
-    end
-
-    def fx_coverage(id)
-      root = File.join(DataLoader.data_root, "fx", "usd")
-      years = Dir[File.join(root, "*.json")].map { |f| File.basename(f, ".json").to_i }.sort
-      return "no data" if years.empty?
-
-      case id
-      when "fx_vnd"
-        # VND broadcast-from-annual covers earlier years too.
-        with_vnd = years.select do |y|
-          d = JSON.parse(File.read(File.join(root, "#{y}.json")))
-          d["rates"].any? { |_, v| v.key?("VND") }
-        end
-        return "no VND data" if with_vnd.empty?
-
-        "USD↔VND #{with_vnd.first}..#{with_vnd.last}"
-      else
-        # ECB pairs (EUR/GBP/JPY) start 1999
-        ecb_years = years.select do |y|
-          d = JSON.parse(File.read(File.join(root, "#{y}.json")))
-          d["rates"].any? { |_, v| v.keys.intersect?(%w[EUR GBP JPY]) }
-        end
-        return "no ECB data" if ecb_years.empty?
-
-        "USD↔EUR/GBP/JPY daily #{ecb_years.first}..#{ecb_years.last}"
-      end
+      ATTRIBUTIONS.map { |s| s.merge(coverage: Coverage.for(s)) }
     end
   end
 end

data/lib/timeprice/supported.rb

@@ -21,8 +21,20 @@ module Timeprice
 
     CURRENCY_TO_COUNTRY = COUNTRY_TO_CURRENCY.invert.freeze
 
+    # Currencies with no minor unit — formatted as whole numbers.
+    ZERO_DECIMAL_CURRENCIES = %w[JPY VND].freeze
+
     module_function
 
+    # ISO 4217 minor-unit count for a currency. Falls back to 2 for unknown
+    # codes so callers can still render *some* value rather than crashing.
+    #
+    # @param currency [String]
+    # @return [Integer]
+    def decimals_for(currency)
+      ZERO_DECIMAL_CURRENCIES.include?(currency.to_s.upcase) ? 0 : 2
+    end
+
     # @param country [String]
     # @return [Boolean]
     def country?(country)
@@ -47,9 +59,4 @@ module Timeprice
       COUNTRY_TO_CURRENCY[country.to_s.upcase]
     end
   end
-
-  # Back-compat aliases — keep the old top-level constants pointing at the
-  # canonical lists so existing requires of "errors" keep working.
-  SUPPORTED_COUNTRIES  = Supported::COUNTRIES
-  SUPPORTED_CURRENCIES = Supported::CURRENCIES
 end

data/lib/timeprice/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Timeprice
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: timeprice
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Patrick
@@ -157,13 +157,20 @@ files:
 - exe/timeprice
 - lib/timeprice.rb
 - lib/timeprice/cli.rb
+- lib/timeprice/cli/formatting.rb
+- lib/timeprice/cli/presenters/compare.rb
+- lib/timeprice/cli/presenters/exchange.rb
+- lib/timeprice/cli/presenters/inflation.rb
+- lib/timeprice/cli/presenters/sources.rb
 - lib/timeprice/compare.rb
+- lib/timeprice/cpi_lookup.rb
 - lib/timeprice/data_loader.rb
 - lib/timeprice/errors.rb
 - lib/timeprice/exchange.rb
 - lib/timeprice/inflation.rb
 - lib/timeprice/point.rb
 - lib/timeprice/sources.rb
+- lib/timeprice/sources/coverage.rb
 - lib/timeprice/supported.rb
 - lib/timeprice/version.rb
 homepage: https://github.com/patrick204nqh/timeprice