timeprice 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0ebaf1340f0abefa6b4dcae31f7d2f2d22021155d24ebc258f15b0495f7a480
-  data.tar.gz: 6068762094c6008c72f4dd7becb10e1e8cb0d0c17b668234e8e0dff84c494cc2
+  metadata.gz: 3b400f9dc1652d4476d884f59a2721e4f07338e76c5cc7afab50896267e1123c
+  data.tar.gz: 1a894e2464aa1f1495ddaa24c284b819a8afc07309cd3080f7c8c70744959ef2
 SHA512:
-  metadata.gz: fa08a556599384d4ae292064b2342bfdc6976eac3fea784afb7426d623fdd0c8ee43001135bd2f7c3a065e735db8dd6d347459144e44ee702f30505ee23c3c1f
-  data.tar.gz: 9fd49be55c8790b4a1adfd9350fdd2e6eed82cdcbf8e41c2dd3b1e1514e5b81f9ffa71dc0a9b530738ac2f2d6fa22e969c240bd81dac043e4a4b8e23b21b6924
+  metadata.gz: 1f2c0b9ae5a4f8de71bdfdfb28f911b676773d406f86149b0c12ad5fbeb002ad51e42d43ed9f21d41c6ddd1a5b2760c2df58796759f66e7b78ac0dc784cee971
+  data.tar.gz: 8dc9e2ff73ddf7d0126538794bb4612a8709881628b713a1e878fe8fba7eddd510597f5a4f0a07e8c9d3b63cc751880df9150db208616f7fc52306ae2474bd10

data/CHANGELOG.md

@@ -5,6 +5,69 @@ 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
+- `Timeprice::Point` value object for compare inputs; `Point.coerce` accepts `Point` instances or 2-tuples in either `[currency, date]` or `[date, currency]` order.
+- `Timeprice::Supported` module — canonical home for `COUNTRIES`, `CURRENCIES`, and the bidirectional currency↔country map. Replaces the duplicated maps in `Compare` and the CLI's `InflationResult` monkey-patch.
+- `Sources::Base` class extracted from the CPI fetchers; `BLS`, `ONS`, and `Eurostat` now subclass it and implement only `fetch` returning `[monthly, annual]`. The drift-check, rebase, merge, write, and summary-log flow is shared.
+- Per-fetcher GitHub Actions `::warning file=…,title=…::` annotations in `scripts/update_data.rb`, so individual fetcher failures show up on the workflow run with a link to the responsible source file.
+- README "Using from Rails / Rake" section covering service objects, Sidekiq, Rake tasks, and `TIMEPRICE_DATA_ROOT`.
+- YARD documentation on the public API (`Timeprice.{inflation,exchange,compare}`, `Inflation`, `Exchange`, `Compare`, `DataLoader`, `Sources`, error classes, `Supported`, `Point`).
+
+### Changed
+- `SUPPORTED_COUNTRIES` / `SUPPORTED_CURRENCIES` are now thin aliases for `Supported::COUNTRIES` / `Supported::CURRENCIES`; existing consumers keep working unchanged.
+- `Compare::CURRENCY_TO_COUNTRY` is now an alias for `Supported::CURRENCY_TO_COUNTRY`.
+
 ## [0.1.2] - 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
@@ -155,6 +164,91 @@ inflated = Timeprice.inflation(amount: 100, from: "2010", to: "2024", country: "
 converted = Timeprice.exchange(amount: inflated, from: "USD", to: "VND", date: "2024-06-30").amount
 ```
 
+## Using from Rails / Rake
+
+`timeprice` is a plain Ruby library — no Railtie, no engine, no autoload magic. It works
+the same way as `BigDecimal` or `JSON`: require it once, call the module functions.
+
+### In a Rails app
+
+Add the gem to your `Gemfile`:
+
+```ruby
+gem "timeprice", "~> 0.1"
+```
+
+Then call it directly from controllers, jobs, presenters, or service objects. The library
+is thread-safe (data files are loaded once and cached as frozen hashes), so it's safe to
+call from threaded servers (Puma) and Sidekiq workers:
+
+```ruby
+# app/services/historical_price.rb
+class HistoricalPrice
+  def self.in_today_dollars(amount, year)
+    Timeprice.inflation(
+      amount: amount,
+      from: year.to_s,
+      to: Date.current.strftime("%Y-%m"),
+      country: "US"
+    ).amount
+  end
+end
+```
+
+Errors all inherit from `Timeprice::Error`, so a single rescue covers everything:
+
+```ruby
+rescue Timeprice::Error => e
+  Rails.logger.warn("timeprice lookup failed: #{e.message}")
+  nil
+end
+```
+
+Result objects respond to `#to_h`, so they serialize cleanly in JSON APIs:
+
+```ruby
+def show
+  render json: Timeprice.exchange(amount: 100, from: "USD", to: "EUR", date: params[:date]).to_h
+end
+```
+
+### In a Rake task
+
+```ruby
+# lib/tasks/inflation.rake
+require "timeprice"
+
+namespace :inflation do
+  desc "Print 1990→today inflation for the supported countries"
+  task :report do
+    today = Date.today.strftime("%Y-%m")
+    %w[US UK EU JP VN].each do |c|
+      r = Timeprice.inflation(amount: 100, from: "1990", to: today, country: c)
+      puts "#{c}: 100 in 1990 → #{r.amount.round(2)} in #{today} (#{r.granularity})"
+    end
+  end
+end
+```
+
+### Configuring the data root
+
+By default the gem reads from its bundled `data/` directory. To point at a different
+checkout (useful for testing a new data refresh before releasing it), set
+`TIMEPRICE_DATA_ROOT`:
+
+```bash
+TIMEPRICE_DATA_ROOT=/path/to/timeprice/data bundle exec rake inflation:report
+```
+
+Or programmatically:
+
+```ruby
+Timeprice::DataLoader.data_root = "/path/to/timeprice/data"
+```
+
+Reassigning `data_root` clears the in-memory cache, so it's safe to call between requests
+in development.
+
 ## Data sources & attribution
 
 `timeprice` redistributes data from several public sources. Each is governed by its own

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