timeprice 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b1b427948a0943958a53ce1820f72eb27b7dc41de61c9e216194aae9c03183d
-  data.tar.gz: 5daac2f9428564420379cc33db7893a8b9dbf0f0344355c1439636e8abf647a7
+  metadata.gz: b0ebaf1340f0abefa6b4dcae31f7d2f2d22021155d24ebc258f15b0495f7a480
+  data.tar.gz: 6068762094c6008c72f4dd7becb10e1e8cb0d0c17b668234e8e0dff84c494cc2
 SHA512:
-  metadata.gz: 14ec61a1a5cc71b33fb0de18bbbfc19ec152697d4f8ddcd2f14cf2d739e80571512ccb067d939f60207c0b2abc2971a03f32272cd2468d273782a1022d9d0dbb
-  data.tar.gz: 5d7fae9eb6583d38f2245830aa66a0ce61fec10aa02cdec600005aea185635d0312c80a7d3bec62f0067a42651839a2af4de4d3c67335b1eb2a649dfe35b2419
+  metadata.gz: fa08a556599384d4ae292064b2342bfdc6976eac3fea784afb7426d623fdd0c8ee43001135bd2f7c3a065e735db8dd6d347459144e44ee702f30505ee23c3c1f
+  data.tar.gz: 9fd49be55c8790b4a1adfd9350fdd2e6eed82cdcbf8e41c2dd3b1e1514e5b81f9ffa71dc0a9b530738ac2f2d6fa22e969c240bd81dac043e4a4b8e23b21b6924

data/CHANGELOG.md

@@ -5,6 +5,30 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-05-11
+
+### Added
+- RuboCop with `rubocop-rake` + `rubocop-rspec`, wired into Rake (`rake default` runs spec + rubocop) and CI (separate `RuboCop` job alongside `RSpec`).
+
+### Changed
+- `DataLoader.load_cpi` now distinguishes between "country isn't supported" (`UnsupportedCountry`) and "data file is missing on disk" (`DataNotFound` with the path the loader looked at). Previously both surfaced as `UnsupportedCountry`, masking install / `TIMEPRICE_DATA_ROOT` misconfigurations.
+- `Timeprice.exchange` now rejects invalid calendar dates (e.g. `2021-02-29`) with `ArgumentError` instead of leaking a `Date::Error`. Honors the public error contract.
+- Trimmed `ZERO_DECIMAL_CURRENCIES` to currencies actually supported by the gem (JPY, VND). Removed aspirational entries (KRW, IDR, HUF, CLP).
+- Inline source comments now reference README sections (`README.md "Compare semantics"`) instead of `PLAN.md` (which is intentionally not shipped in the gem).
+- `CONTRIBUTING.md` updated to match the single-Ruby CI; both `rspec` and `rubocop` must be green.
+
+
+
+### Changed
+- CLI output formatting: currency-aware decimals (no `.0000` on JPY/VND), magnitude-aware FX rate precision (no `91.180000` for a 91.18 rate).
+- `granularity` is omitted from human output when it's `monthly` (the happy path); surfaced only when the result used annual data.
+- Error messages hint at supported values: `Unsupported country: "FR" (supported: US, UK, EU, JP, VN)`; out-of-range CPI errors include the actual coverage range.
+- Validate FX currencies against the supported list up front instead of failing with a generic "no FX rate" message.
+- Tightened CLI command descriptions so `timeprice help` fits in a standard terminal.
+
+### Fixed
+- Hide Thor's built-in `tree` command — it was leaking into `timeprice help` as an internal-looking debug command.
+
 ## [0.1.0] - 2026-05-11
 
 ### Added

data/lib/timeprice/cli.rb

@@ -6,15 +6,23 @@ require_relative "../timeprice"
 
 module Timeprice
   class CLI < Thor
+    # Thor 1.5 ships a built-in `tree` command on every subclass. Strip it
+    # from this subclass — it's an internal debugging aid that leaks into
+    # our help output. all_commands inherits from the base Thor class, so
+    # filter it on read.
+    def self.all_commands
+      super.except("tree")
+    end
+
     class_option :json, type: :boolean, default: false, desc: "Output result as JSON"
 
     def self.exit_on_failure?
       true
     end
 
-    desc "inflation AMOUNT", "Adjust AMOUNT for inflation between two dates"
-    method_option :from, type: :string, required: true, desc: "Source date (YYYY or YYYY-MM)"
-    method_option :to,   type: :string, required: true, desc: "Target date (YYYY or YYYY-MM)"
+    desc "inflation AMOUNT", "Inflation-adjust an amount between two dates"
+    method_option :from,    type: :string, required: true, desc: "Source date (YYYY or YYYY-MM)"
+    method_option :to,      type: :string, required: true, desc: "Target date (YYYY or YYYY-MM)"
     method_option :country, type: :string, required: true, desc: "Country code (US, UK, EU, JP, VN)"
     def inflation(amount)
       with_error_handling do
@@ -28,7 +36,7 @@ module Timeprice
       end
     end
 
-    desc "fx AMOUNT FROM_CURRENCY TO_CURRENCY", "Convert AMOUNT between currencies on a given date"
+    desc "fx AMOUNT FROM TO", "Convert an amount between currencies on a date"
     method_option :date, type: :string, required: true, desc: "Date (YYYY-MM-DD)"
     def fx(amount, from_currency, to_currency)
       with_error_handling do
@@ -58,14 +66,14 @@ module Timeprice
       end
     end
 
-    desc "sources", "List bundled data sources, licenses, attribution, and coverage"
+    desc "sources", "List bundled data sources and coverage"
     def sources
       list = Timeprice::Sources.list
       if options[:json]
         say JSON.generate(list)
       else
         list.each do |s|
-          say "#{s[:name]}"
+          say s[:name].to_s
           say "  id:           #{s[:id]}"
           say "  license:      #{s[:license]}"
           say "  license_url:  #{s[:license_url]}"
@@ -86,21 +94,22 @@ module Timeprice
     end
 
     no_commands do
+      # Currencies with no minor unit — render whole numbers, no decimals.
+      ZERO_DECIMAL_CURRENCIES = %w[JPY VND].freeze
+
       def with_error_handling
         yield
       rescue Timeprice::Error => e
         warn "Error: #{e.message}"
         exit 1
       rescue ArgumentError => e
-        # Bad numeric/date format from Float() or library parsers — treat as user error.
         warn "Error: #{e.message}"
         exit 1
       end
 
-      # Accepts "1995 USD" or "USD 1995" — order-agnostic.
-      # Returns [currency, year_string] tuple matching Timeprice.compare's API.
       def parse_compare_token(token, label:)
         raise ArgumentError, "#{label} is required" if token.nil? || token.strip.empty?
+
         parts = token.strip.split(/\s+/)
         unless parts.size == 2
           raise ArgumentError,
@@ -115,15 +124,39 @@ module Timeprice
         [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(
-            "%.2f %s in %s is %.2f %s in %s (%s, granularity: %s)",
-            result.original_amount, result.country_currency_label,
-            result.from, result.amount, result.country_currency_label,
-            result.to, result.country, result.granularity
+            "%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
@@ -133,12 +166,12 @@ module Timeprice
           say JSON.generate(result.to_h)
         else
           line = format(
-            "%.2f %s on %s = %.2f %s (rate: %.4f)",
-            result.original_amount, result.from, result.date,
-            result.amount, result.to, result.rate
+            "%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 date: #{result.effective_date} — fallback)"
+            line += " [effective: #{result.effective_date}, fallback]"
           end
           say line
         end
@@ -149,14 +182,16 @@ module Timeprice
           say JSON.generate(result.to_h)
         else
           say format(
-            "%.2f %s in %s -> %.2f %s in %s",
-            result.original_amount, result.from_currency, result.from_date,
-            result.amount, result.to_currency, result.to_date
+            "%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: convert at %s (fx rate %.6f) -> %.4f %s, then inflate in %s (cpi ratio %.6f, granularity: %s)",
-            result.from_date, result.fx_rate, result.converted_amount,
-            result.to_currency, result.country, result.cpi_ratio, result.granularity
+            "  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
       end

data/lib/timeprice/compare.rb

@@ -16,7 +16,7 @@ module Timeprice
   # Compare combines FX and inflation across two (currency, date) points.
   #
   # CONVENTION (critical): convert at SOURCE date first, then inflate in
-  # destination currency. See PLAN.md §2 last bullet and §7.
+  # destination currency. See README.md "Compare semantics" section.
   #
   # This preserves purchasing-power equivalence in the destination economy.
   # The naive alternative (inflate in source currency first, then convert at
@@ -32,7 +32,7 @@ module Timeprice
       "GBP" => "UK",
       "EUR" => "EU",
       "JPY" => "JP",
-      "VND" => "VN"
+      "VND" => "VN",
     }.freeze
 
     module_function
@@ -78,7 +78,7 @@ module Timeprice
         to_date: to_date.to_s,
         country: to_country,
         fx_rate: fx_result.rate,
-        cpi_ratio: infl.to_index.to_f / infl.from_index.to_f,
+        cpi_ratio: infl.to_index.to_f / infl.from_index,
         converted_amount: converted,
         granularity: infl.granularity
       )

data/lib/timeprice/data_loader.rb

@@ -27,9 +27,16 @@ module Timeprice
       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)
+
           path = File.join(data_root, "cpi", "#{key}.json")
-          raise UnsupportedCountry, country.to_s.upcase unless File.exist?(path)
+          unless File.exist?(path)
+            raise DataNotFound, "CPI data file missing for #{code} (looked in #{path}). " \
+                                "Check TIMEPRICE_DATA_ROOT or reinstall the gem."
+          end
+
           parse_with_schema(path)
         end
       end
@@ -40,6 +47,7 @@ module Timeprice
         @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)
+
           parse_with_schema(path)
         end
       end
@@ -49,9 +57,8 @@ module Timeprice
       def parse_with_schema(path)
         data = JSON.parse(File.read(path))
         version = data["schema_version"]
-        unless version == SUPPORTED_SCHEMA_VERSION
-          raise UnsupportedSchemaVersion.new(version, path)
-        end
+        raise UnsupportedSchemaVersion.new(version, path) unless version == SUPPORTED_SCHEMA_VERSION
+
         data
       end
     end

data/lib/timeprice/errors.rb

@@ -3,12 +3,15 @@
 module Timeprice
   class Error < StandardError; end
 
+  SUPPORTED_COUNTRIES = %w[US UK EU JP VN].freeze
+  SUPPORTED_CURRENCIES = %w[USD GBP EUR JPY VND].freeze
+
   class UnsupportedCountry < Error
     attr_reader :country
 
     def initialize(country)
       @country = country
-      super("Unsupported country: #{country.inspect}")
+      super("Unsupported country: #{country.inspect} (supported: #{SUPPORTED_COUNTRIES.join(", ")})")
     end
   end
 
@@ -17,7 +20,7 @@ module Timeprice
 
     def initialize(currency)
       @currency = currency
-      super("Unsupported currency: #{currency.inspect}")
+      super("Unsupported currency: #{currency.inspect} (supported: #{SUPPORTED_CURRENCIES.join(", ")})")
     end
   end
 

data/lib/timeprice/exchange.rb

@@ -20,6 +20,9 @@ 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)
+
       d = parse_date(date)
 
       rate, eff_date = resolve_rate(from, to, d)
@@ -75,8 +78,10 @@ module Timeprice
           end
         rates_for_day = year_data.dig("rates", candidate.to_s)
         next unless rates_for_day
+
         rate = rates_for_day[currency]
         next unless rate
+
         return [rate.to_f, candidate]
       end
       raise DataNotFound, "No FX rate for USD->#{currency} on or before #{d}"
@@ -89,7 +94,12 @@ module Timeprice
         unless date.match?(/\A\d{4}-\d{2}-\d{2}\z/)
           raise ArgumentError, "Invalid date format: #{date.inspect} (use YYYY-MM-DD)"
         end
-        Date.parse(date)
+
+        begin
+          Date.parse(date)
+        rescue Date::Error
+          raise ArgumentError, "Invalid date: #{date.inspect} is not a real calendar date"
+        end
       else
         raise ArgumentError, "Invalid date: #{date.inspect}"
       end

data/lib/timeprice/inflation.rb

@@ -27,7 +27,7 @@ module Timeprice
       from_index, from_gran = lookup_index(data, from)
       to_index,   to_gran   = lookup_index(data, to)
 
-      ratio = to_index.to_f / from_index.to_f
+      ratio = to_index.to_f / from_index
       InflationResult.new(
         amount: amount.to_f * ratio,
         original_amount: amount.to_f,
@@ -58,18 +58,18 @@ module Timeprice
           [monthly[key], :monthly]
         else
           year = key[0, 4]
-          if annual.key?(year)
-            [annual[year], :annual]
-          else
-            raise DataNotFound, "No CPI data for #{key.inspect} in #{data["country"]}"
-          end
+          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, "No CPI data for #{key.inspect} in #{data["country"]}" if months.empty?
+          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
@@ -78,11 +78,27 @@ module Timeprice
       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)
       return :annual_from_monthly_avg if a == :annual_from_monthly_avg || b == :annual_from_monthly_avg
       return :annual if a == :annual || b == :annual
+
       :monthly
     end
   end

data/lib/timeprice/sources.rb

@@ -15,7 +15,7 @@ module Timeprice
         name: "U.S. Bureau of Labor Statistics — CPI-U (series CUUR0000SA0)",
         license: "U.S. Government work — public domain",
         license_url: "https://www.bls.gov/bls/linksite.htm",
-        attribution: "Data: U.S. Bureau of Labor Statistics"
+        attribution: "Data: U.S. Bureau of Labor Statistics",
       },
       {
         id: "uk_cpi",
@@ -24,7 +24,7 @@ module Timeprice
         name: "UK Office for National Statistics — CPI all-items (series D7BT)",
         license: "Open Government Licence v3.0",
         license_url: "https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/",
-        attribution: "Contains public sector information licensed under the Open Government Licence v3.0"
+        attribution: "Contains public sector information licensed under the Open Government Licence v3.0",
       },
       {
         id: "eu_hicp",
@@ -33,7 +33,7 @@ module Timeprice
         name: "Eurostat — HICP prc_hicp_midx (Euro area, all items)",
         license: "Eurostat reuse policy (free reuse with attribution)",
         license_url: "https://ec.europa.eu/eurostat/about-us/policies/copyright",
-        attribution: "Source: Eurostat"
+        attribution: "Source: Eurostat",
       },
       {
         id: "jp_cpi",
@@ -42,7 +42,7 @@ module Timeprice
         name: "World Bank — FP.CPI.TOTL (annual, JP fallback)",
         license: "CC BY 4.0",
         license_url: "https://datacatalog.worldbank.org/public-licenses#cc-by",
-        attribution: "Source: World Bank, FP.CPI.TOTL"
+        attribution: "Source: World Bank, FP.CPI.TOTL",
       },
       {
         id: "vn_cpi",
@@ -51,7 +51,7 @@ module Timeprice
         name: "World Bank — FP.CPI.TOTL (annual)",
         license: "CC BY 4.0",
         license_url: "https://datacatalog.worldbank.org/public-licenses#cc-by",
-        attribution: "Source: World Bank, FP.CPI.TOTL"
+        attribution: "Source: World Bank, FP.CPI.TOTL",
       },
       {
         id: "fx_ecb",
@@ -60,7 +60,7 @@ module Timeprice
         name: "European Central Bank reference rates (via Frankfurter)",
         license: "ECB reference rates — free reuse",
         license_url: "https://www.ecb.europa.eu/services/disclaimer/html/index.en.html",
-        attribution: "FX data: European Central Bank reference rates via Frankfurter"
+        attribution: "FX data: European Central Bank reference rates via Frankfurter",
       },
       {
         id: "fx_vnd",
@@ -69,8 +69,8 @@ module Timeprice
         name: "World Bank — PA.NUS.FCRF (VND annual average, broadcast daily)",
         license: "CC BY 4.0",
         license_url: "https://datacatalog.worldbank.org/public-licenses#cc-by",
-        attribution: "VND FX: World Bank, PA.NUS.FCRF"
-      }
+        attribution: "VND FX: World Bank, PA.NUS.FCRF",
+      },
     ].freeze
 
     module_function
@@ -105,6 +105,7 @@ module Timeprice
       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.
@@ -113,14 +114,16 @@ module Timeprice
           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 & %w[EUR GBP JPY]).any? }
+          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
     end

data/lib/timeprice/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: timeprice
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Patrick
@@ -51,6 +51,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.69'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.69'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
 description: Offline historical inflation & FX for Ruby - bundled data, no API keys,
   monthly auto-refresh.
 email:
@@ -130,6 +172,7 @@ metadata:
   bug_tracker_uri: https://github.com/patrick204nqh/timeprice/issues
   changelog_uri: https://github.com/patrick204nqh/timeprice/blob/main/CHANGELOG.md
   github_repo: patrick204nqh/timeprice
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib