timeprice 0.3.0 → 0.5.0

data/lib/timeprice/granularity.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Timeprice
+  # Closed set of CPI-resolution granularities and the rules for combining /
+  # rendering them. Owns the lattice so callers don't hand-maintain it.
+  module Granularity
+    DAILY                        = :daily
+    MONTHLY                      = :monthly
+    ANNUAL                       = :annual
+    ANNUAL_FROM_MONTHLY_AVG      = :annual_from_monthly_avg
+    MONTHLY_FROM_ANNUAL_FALLBACK = :monthly_from_annual_fallback
+
+    # Most-degraded first — `merge` returns the first match.
+    # DAILY is the highest-precision FX tag; MONTHLY is the highest-precision
+    # CPI tag. Compare uses merge() across both legs, so the most-degraded
+    # tag in either leg wins.
+    PRECEDENCE = [
+      MONTHLY_FROM_ANNUAL_FALLBACK,
+      ANNUAL_FROM_MONTHLY_AVG,
+      ANNUAL,
+      MONTHLY,
+      DAILY,
+    ].freeze
+
+    HUMAN_LABELS = {
+      DAILY => "daily",
+      MONTHLY => "monthly",
+      ANNUAL => "annual",
+      ANNUAL_FROM_MONTHLY_AVG => "annual (avg of months)",
+      MONTHLY_FROM_ANNUAL_FALLBACK => "annual (month unavailable)",
+    }.freeze
+
+    module_function
+
+    # Worst-precision-wins merge across two or more endpoint granularities.
+    def merge(*tags)
+      PRECEDENCE.find { |t| tags.include?(t) } || MONTHLY
+    end
+
+    # Human-readable label for CLI output. Falls through to the symbol's
+    # string form so an unknown tag still renders something.
+    def humanize(tag)
+      HUMAN_LABELS.fetch(tag, tag.to_s)
+    end
+  end
+end

data/lib/timeprice/inflation.rb

@@ -3,15 +3,11 @@
 require_relative "errors"
 require_relative "data_loader"
 require_relative "cpi_lookup"
+require_relative "granularity"
 
 module Timeprice
-  # Value object returned by Inflation.adjust.
-  #
-  # granularity is one of:
-  #   :monthly                  — both ends resolved on monthly data
-  #   :annual                   — at least one end resolved on annual data
-  #   :annual_from_monthly_avg  — at least one end was an annual request resolved
-  #                               by averaging 12 months of monthly data
+  # Value object returned by Inflation.adjust. See {Granularity} for the set
+  # of possible `granularity` values and the worst-precision-wins merge rule.
   InflationResult = Data.define(
     :amount, :original_amount, :from, :to, :country,
     :from_index, :to_index, :granularity
@@ -25,7 +21,7 @@ module Timeprice
     end
   end
 
-  # CPI-based inflation adjustment for the {Supported::COUNTRIES} list.
+  # CPI-based inflation adjustment for the {Supported.countries} list.
   module Inflation
     module_function
 
@@ -36,7 +32,7 @@ module Timeprice
     # @param amount  [Numeric]
     # @param from    [String] source date ("YYYY" or "YYYY-MM")
     # @param to      [String] target date ("YYYY" or "YYYY-MM")
-    # @param country [String] country code (see {Supported::COUNTRIES})
+    # @param country [String] country code (see {Supported.countries})
     # @return [InflationResult]
     # @raise [UnsupportedCountry] if `country` is not supported
     # @raise [DataNotFound]       if no CPI data covers the requested period
@@ -54,7 +50,7 @@ module Timeprice
         country: country.to_s.upcase,
         from_index: from_point.value,
         to_index: to_point.value,
-        granularity: merge_granularity(from_point.granularity, to_point.granularity)
+        granularity: Granularity.merge(from_point.granularity, to_point.granularity)
       )
     end
 
@@ -68,14 +64,5 @@ module Timeprice
       result = adjust(amount: 1.0, from: from, to: to, country: country)
       result.amount - 1.0
     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
 end

data/lib/timeprice/sources/coverage.rb

@@ -5,9 +5,10 @@ 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.
+    # Computes coverage strings for bundled data sources at runtime by reading
+    # the structured `provenance` blocks in v3 data files. The Sources
+    # attribution registry stays a pure data table; Coverage is the only
+    # place that touches the filesystem.
     module Coverage
       module_function
 
@@ -25,46 +26,40 @@ module Timeprice
 
       def cpi(country)
         data = DataLoader.load_cpi(country)
-        monthly = (data["monthly"] || {}).keys.sort
-        annual  = (data["annual"]  || {}).keys.sort
+        monthly = data.dig("series", "monthly") || {}
+        annual  = data.dig("series", "annual") || {}
         parts = []
-        parts << "monthly #{monthly.first}..#{monthly.last} (#{monthly.size})" unless monthly.empty?
-        parts << "annual #{annual.first}..#{annual.last} (#{annual.size})" unless annual.empty?
+        parts << "monthly #{monthly.keys.min}..#{monthly.keys.max} (#{monthly.size})" if monthly.any?
+        parts << "annual #{annual.keys.min}..#{annual.keys.max} (#{annual.size})" if annual.any?
         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}"
+        case id
+        when "fx_ecb" then ecb_summary
+        when "fx_vnd" then vnd_summary
+        else "n/a"
+        end
       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?
+      # Frankfurter (ECB) → daily EUR/GBP/JPY in per-year files. Range derived
+      # from the manifest's `daily_years` list.
+      def ecb_summary
+        years = DataLoader.load_manifest.dig("fx", "daily_years") || []
+        return "no ECB data" if years.empty?
 
-        "USD↔EUR/GBP/JPY daily #{ecb_years.first}..#{ecb_years.last}"
+        "USD↔EUR/GBP/JPY daily #{years.first}..#{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
+      # All annual FX (today only VND) lives in data/fx/usd/_annual.json.
+      def vnd_summary
+        fallback = DataLoader.load_fx_annual_fallback
+        years = (fallback&.dig("annual") || {})
+                .select { |_y, ccy_hash| ccy_hash.key?("VND") }
+                .keys.map(&:to_i).sort
+        return "no VND data" if years.empty?
 
-      def fx_root
-        File.join(DataLoader.data_root, "fx", "usd")
+        "USD↔VND #{years.first}..#{years.last}"
       end
     end
   end

data/lib/timeprice/sources.rb

@@ -48,10 +48,10 @@ module Timeprice
         id: "vn_cpi",
         kind: "cpi",
         country: "VN",
-        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",
+        name: "IMF Data Portal CPI dataflow (monthly primary) + World Bank FP.CPI.TOTL (annual fallback)",
+        license: "IMF: free reuse with attribution; World Bank: CC BY 4.0",
+        license_url: "https://www.imf.org/external/terms.htm",
+        attribution: "Sources: IMF Data Portal CPI dataflow; World Bank FP.CPI.TOTL",
       },
       {
         id: "fx_ecb",
@@ -66,7 +66,7 @@ module Timeprice
         id: "fx_vnd",
         kind: "fx",
         country: "VN",
-        name: "World Bank — PA.NUS.FCRF (VND annual average, broadcast daily)",
+        name: "World Bank — PA.NUS.FCRF (VND annual average, annual-granularity fallback)",
         license: "CC BY 4.0",
         license_url: "https://datacatalog.worldbank.org/public-licenses#cc-by",
         attribution: "VND FX: World Bank, PA.NUS.FCRF",

data/lib/timeprice/supported.rb

@@ -1,34 +1,43 @@
 # frozen_string_literal: true
 
 module Timeprice
-  # Canonical lists of supported country and currency codes, plus the
-  # bidirectional currency↔country map used by `Compare` and CLI output.
+  # Supported country and currency codes, derived from `data/manifest.json`.
+  # Adding a country = drop a CPI file + regenerate the manifest. No code
+  # change required.
   #
   # Everything that needs to know "which currency pairs with which CPI series"
-  # must read it from here — duplicating the map elsewhere has bitten us before
-  # when a new country was added in one place and forgotten in the other.
+  # must read it from here.
   module Supported
-    COUNTRIES  = %w[US UK EU JP VN].freeze
-    CURRENCIES = %w[USD GBP EUR JPY VND].freeze
+    # Currencies with no minor unit — formatted as whole numbers. This is
+    # ISO 4217 metadata, not bundled data, so it stays hardcoded.
+    ZERO_DECIMAL_CURRENCIES = %w[JPY VND].freeze
 
-    COUNTRY_TO_CURRENCY = {
-      "US" => "USD",
-      "UK" => "GBP",
-      "EU" => "EUR",
-      "JP" => "JPY",
-      "VN" => "VND",
-    }.freeze
+    module_function
 
-    CURRENCY_TO_COUNTRY = COUNTRY_TO_CURRENCY.invert.freeze
+    # @return [Array<String>] frozen list of supported country codes.
+    def countries
+      manifest_countries.map { |c| c["code"] }.freeze
+    end
 
-    # Currencies with no minor unit — formatted as whole numbers.
-    ZERO_DECIMAL_CURRENCIES = %w[JPY VND].freeze
+    # @return [Array<String>] frozen list of supported currency codes
+    #   (the FX base USD plus every currency the manifest declares).
+    def currencies
+      base = DataLoader.load_manifest.dig("fx", "base")
+      ([base] + DataLoader.load_manifest.dig("fx", "currencies")).uniq.freeze
+    end
 
-    module_function
+    # @return [Hash{String=>String}] country code → currency code.
+    def country_to_currency
+      manifest_countries.to_h { |c| [c["code"], c["currency"]] }.freeze
+    end
+
+    # @return [Hash{String=>String}] currency code → country code.
+    def currency_to_country
+      country_to_currency.invert.freeze
+    end
 
     # 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)
@@ -38,25 +47,33 @@ module Timeprice
     # @param country [String]
     # @return [Boolean]
     def country?(country)
-      COUNTRIES.include?(country.to_s.upcase)
+      countries.include?(country.to_s.upcase)
     end
 
     # @param currency [String]
     # @return [Boolean]
     def currency?(currency)
-      CURRENCIES.include?(currency.to_s.upcase)
+      currencies.include?(currency.to_s.upcase)
     end
 
     # @param currency [String] ISO 4217 code (e.g. "USD")
     # @return [String, nil] country code, or nil if unsupported
     def country_for_currency(currency)
-      CURRENCY_TO_COUNTRY[currency.to_s.upcase]
+      currency_to_country[currency.to_s.upcase]
     end
 
     # @param country [String] country code (e.g. "US")
     # @return [String, nil] currency code, or nil if unsupported
     def currency_for_country(country)
-      COUNTRY_TO_CURRENCY[country.to_s.upcase]
+      country_to_currency[country.to_s.upcase]
+    end
+
+    class << self
+      private
+
+      def manifest_countries
+        DataLoader.load_manifest["countries"] || []
+      end
     end
   end
 end

data/lib/timeprice/version.rb

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

data/lib/timeprice.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 require_relative "timeprice/version"
+require_relative "timeprice/data_loader"
 require_relative "timeprice/supported"
 require_relative "timeprice/errors"
 require_relative "timeprice/point"
-require_relative "timeprice/data_loader"
 require_relative "timeprice/inflation"
 require_relative "timeprice/exchange"
 require_relative "timeprice/compare"
@@ -30,7 +30,7 @@ module Timeprice
   # @param amount  [Numeric] the original amount
   # @param from    [String]  source date as "YYYY" or "YYYY-MM"
   # @param to      [String]  target date as "YYYY" or "YYYY-MM"
-  # @param country [String]  country code from {Supported::COUNTRIES}
+  # @param country [String]  country code from {Supported.countries}
   # @return [InflationResult]
   # @raise [UnsupportedCountry] if `country` is not supported
   # @raise [DataNotFound]       if no CPI point covers `from` or `to`

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: timeprice
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Patrick
@@ -112,20 +112,6 @@ files:
 - data/cpi/uk.json
 - data/cpi/us.json
 - data/cpi/vn.json
-- data/fx/usd/1983.json
-- data/fx/usd/1986.json
-- data/fx/usd/1987.json
-- data/fx/usd/1988.json
-- data/fx/usd/1989.json
-- data/fx/usd/1990.json
-- data/fx/usd/1991.json
-- data/fx/usd/1992.json
-- data/fx/usd/1993.json
-- data/fx/usd/1994.json
-- data/fx/usd/1995.json
-- data/fx/usd/1996.json
-- data/fx/usd/1997.json
-- data/fx/usd/1998.json
 - data/fx/usd/1999.json
 - data/fx/usd/2000.json
 - data/fx/usd/2001.json
@@ -154,6 +140,8 @@ files:
 - data/fx/usd/2024.json
 - data/fx/usd/2025.json
 - data/fx/usd/2026.json
+- data/fx/usd/_annual.json
+- data/manifest.json
 - exe/timeprice
 - lib/timeprice.rb
 - lib/timeprice/cli.rb
@@ -167,6 +155,7 @@ files:
 - lib/timeprice/data_loader.rb
 - lib/timeprice/errors.rb
 - lib/timeprice/exchange.rb
+- lib/timeprice/granularity.rb
 - lib/timeprice/inflation.rb
 - lib/timeprice/point.rb
 - lib/timeprice/sources.rb

data/data/fx/usd/1983.json

@@ -1,12 +0,0 @@
-{
-  "base": "USD",
-  "rates": {
-    "1983-01-02": {
-      "VND": 1.0
-    }
-  },
-  "schema_version": 1,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY; World Bank PA.NUS.FCRF for VND (annual avg, broadcast to every day in year)",
-  "updated_at": "2026-05-11",
-  "year": 1983
-}

data/data/fx/usd/1986.json

@@ -1,12 +0,0 @@
-{
-  "base": "USD",
-  "rates": {
-    "1986-01-02": {
-      "VND": 22.94
-    }
-  },
-  "schema_version": 1,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY; World Bank PA.NUS.FCRF for VND (annual avg, broadcast to every day in year)",
-  "updated_at": "2026-05-11",
-  "year": 1986
-}

data/data/fx/usd/1987.json

@@ -1,12 +0,0 @@
-{
-  "base": "USD",
-  "rates": {
-    "1987-01-02": {
-      "VND": 78.95
-    }
-  },
-  "schema_version": 1,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY; World Bank PA.NUS.FCRF for VND (annual avg, broadcast to every day in year)",
-  "updated_at": "2026-05-11",
-  "year": 1987
-}

data/data/fx/usd/1988.json

@@ -1,12 +0,0 @@
-{
-  "base": "USD",
-  "rates": {
-    "1988-01-02": {
-      "VND": 611.65
-    }
-  },
-  "schema_version": 1,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY; World Bank PA.NUS.FCRF for VND (annual avg, broadcast to every day in year)",
-  "updated_at": "2026-05-11",
-  "year": 1988
-}

data/data/fx/usd/1989.json

@@ -1,12 +0,0 @@
-{
-  "base": "USD",
-  "rates": {
-    "1989-01-02": {
-      "VND": 4501.69
-    }
-  },
-  "schema_version": 1,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY; World Bank PA.NUS.FCRF for VND (annual avg, broadcast to every day in year)",
-  "updated_at": "2026-05-11",
-  "year": 1989
-}

data/data/fx/usd/1990.json

@@ -1,12 +0,0 @@
-{
-  "base": "USD",
-  "rates": {
-    "1990-01-02": {
-      "VND": 6537.6
-    }
-  },
-  "schema_version": 1,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY; World Bank PA.NUS.FCRF for VND (annual avg, broadcast to every day in year)",
-  "updated_at": "2026-05-11",
-  "year": 1990
-}

data/data/fx/usd/1991.json

@@ -1,12 +0,0 @@
-{
-  "base": "USD",
-  "rates": {
-    "1991-01-02": {
-      "VND": 10121.89
-    }
-  },
-  "schema_version": 1,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY; World Bank PA.NUS.FCRF for VND (annual avg, broadcast to every day in year)",
-  "updated_at": "2026-05-11",
-  "year": 1991
-}

data/data/fx/usd/1992.json

@@ -1,12 +0,0 @@
-{
-  "base": "USD",
-  "rates": {
-    "1992-01-02": {
-      "VND": 11202.19
-    }
-  },
-  "schema_version": 1,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY; World Bank PA.NUS.FCRF for VND (annual avg, broadcast to every day in year)",
-  "updated_at": "2026-05-11",
-  "year": 1992
-}

data/data/fx/usd/1993.json

@@ -1,12 +0,0 @@
-{
-  "base": "USD",
-  "rates": {
-    "1993-01-02": {
-      "VND": 10640.96
-    }
-  },
-  "schema_version": 1,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY; World Bank PA.NUS.FCRF for VND (annual avg, broadcast to every day in year)",
-  "updated_at": "2026-05-11",
-  "year": 1993
-}

data/data/fx/usd/1994.json

@@ -1,12 +0,0 @@
-{
-  "base": "USD",
-  "rates": {
-    "1994-01-02": {
-      "VND": 10965.67
-    }
-  },
-  "schema_version": 1,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY; World Bank PA.NUS.FCRF for VND (annual avg, broadcast to every day in year)",
-  "updated_at": "2026-05-11",
-  "year": 1994
-}

data/data/fx/usd/1995.json

@@ -1,12 +0,0 @@
-{
-  "base": "USD",
-  "rates": {
-    "1995-01-02": {
-      "VND": 11038.25
-    }
-  },
-  "schema_version": 1,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY; World Bank PA.NUS.FCRF for VND (annual avg, broadcast to every day in year)",
-  "updated_at": "2026-05-11",
-  "year": 1995
-}

data/data/fx/usd/1996.json

@@ -1,12 +0,0 @@
-{
-  "base": "USD",
-  "rates": {
-    "1996-01-02": {
-      "VND": 11032.58
-    }
-  },
-  "schema_version": 1,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY; World Bank PA.NUS.FCRF for VND (annual avg, broadcast to every day in year)",
-  "updated_at": "2026-05-11",
-  "year": 1996
-}

data/data/fx/usd/1997.json

@@ -1,12 +0,0 @@
-{
-  "base": "USD",
-  "rates": {
-    "1997-01-02": {
-      "VND": 11683.33
-    }
-  },
-  "schema_version": 1,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY; World Bank PA.NUS.FCRF for VND (annual avg, broadcast to every day in year)",
-  "updated_at": "2026-05-11",
-  "year": 1997
-}

data/data/fx/usd/1998.json

@@ -1,12 +0,0 @@
-{
-  "base": "USD",
-  "rates": {
-    "1998-01-02": {
-      "VND": 13268.0
-    }
-  },
-  "schema_version": 1,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY; World Bank PA.NUS.FCRF for VND (annual avg, broadcast to every day in year)",
-  "updated_at": "2026-05-11",
-  "year": 1998
-}