timeprice 0.4.0 → 0.5.0

data/data/manifest.json

@@ -0,0 +1,90 @@
+{
+  "countries": [
+    {
+      "code": "EU",
+      "cpi_file": "cpi/eu.json",
+      "currency": "EUR",
+      "granularities": [
+        "monthly",
+        "annual"
+      ]
+    },
+    {
+      "code": "JP",
+      "cpi_file": "cpi/jp.json",
+      "currency": "JPY",
+      "granularities": [
+        "annual"
+      ]
+    },
+    {
+      "code": "UK",
+      "cpi_file": "cpi/uk.json",
+      "currency": "GBP",
+      "granularities": [
+        "monthly",
+        "annual"
+      ]
+    },
+    {
+      "code": "US",
+      "cpi_file": "cpi/us.json",
+      "currency": "USD",
+      "granularities": [
+        "monthly",
+        "annual"
+      ]
+    },
+    {
+      "code": "VN",
+      "cpi_file": "cpi/vn.json",
+      "currency": "VND",
+      "granularities": [
+        "monthly",
+        "annual"
+      ]
+    }
+  ],
+  "fx": {
+    "annual_file": "fx/usd/_annual.json",
+    "base": "USD",
+    "currencies": [
+      "EUR",
+      "GBP",
+      "JPY",
+      "VND"
+    ],
+    "daily_years": [
+      1999,
+      2000,
+      2001,
+      2002,
+      2003,
+      2004,
+      2005,
+      2006,
+      2007,
+      2008,
+      2009,
+      2010,
+      2011,
+      2012,
+      2013,
+      2014,
+      2015,
+      2016,
+      2017,
+      2018,
+      2019,
+      2020,
+      2021,
+      2022,
+      2023,
+      2024,
+      2025,
+      2026
+    ]
+  },
+  "generated_at": "2026-05-11",
+  "schema_version": 3
+}

data/lib/timeprice/compare.rb

@@ -38,7 +38,7 @@ module Timeprice
     #   accepts a {Point} or a 2-tuple like `["USD", "2010"]` or `["USD", "2010-06"]`
     # @param to     [Timeprice::Point, Array(String, String)] destination point
     # @return [CompareResult]
-    # @raise [UnsupportedCurrency] if either currency is not in {Supported::CURRENCIES}
+    # @raise [UnsupportedCurrency] if either currency is not in {Supported.currencies}
     def run(amount:, from:, to:)
       from_point, to_point, to_country = resolve_points(from, to)
 

data/lib/timeprice/cpi_lookup.rb

@@ -14,8 +14,8 @@ module Timeprice
   class CpiLookup
     def initialize(data)
       @data = data
-      @monthly = data["monthly"] || {}
-      @annual  = data["annual"]  || {}
+      @monthly = data.dig("series", "monthly") || {}
+      @annual  = data.dig("series", "annual")  || {}
     end
 
     # @param key [String] "YYYY" or "YYYY-MM"

data/lib/timeprice/data_loader.rb

@@ -2,19 +2,18 @@
 
 require "json"
 require_relative "errors"
-require_relative "supported"
 
 module Timeprice
   # Loads and caches the bundled JSON data files. Override the search root
   # by setting `TIMEPRICE_DATA_ROOT` in the environment or assigning
   # {DataLoader.data_root=}.
   module DataLoader
-    SUPPORTED_SCHEMA_VERSION = 2
+    SUPPORTED_SCHEMA_VERSION = 3
 
     DEFAULT_DATA_ROOT = File.expand_path("../../data", __dir__)
 
     class << self
-      # @return [String] absolute path to the directory containing `cpi/` and `fx/`
+      # @return [String] absolute path to the directory containing `cpi/`, `fx/`, `manifest.json`.
       def data_root
         ENV["TIMEPRICE_DATA_ROOT"] || @data_root || DEFAULT_DATA_ROOT
       end
@@ -32,19 +31,36 @@ module Timeprice
       def clear_cache!
         @cpi_cache = {}
         @fx_cache = {}
+        @manifest_cache = {}
+        @annual_fallback_cache = {}
+      end
+
+      # Load the top-level manifest describing the bundled dataset.
+      # @return [Hash]
+      # @raise [DataNotFound] if `manifest.json` is missing
+      def load_manifest
+        manifest_cache[data_root] ||= begin
+          path = File.join(data_root, "manifest.json")
+          unless File.exist?(path)
+            raise DataNotFound, "manifest.json missing (looked in #{path}). " \
+                                "Check TIMEPRICE_DATA_ROOT or reinstall the gem."
+          end
+
+          parse_with_schema(path)
+        end
       end
 
       # Load the CPI series for a supported country.
       # @param country [String]
-      # @return [Hash] parsed JSON with "monthly" / "annual" / metadata keys
-      # @raise [UnsupportedCountry] if `country` is not in {Supported::COUNTRIES}
+      # @return [Hash] parsed JSON with "series" / "index" / "provenance" / "providers"
+      # @raise [UnsupportedCountry] if `country` is not in {Supported.countries}
       # @raise [DataNotFound]       if the file is missing
       # @raise [UnsupportedSchemaVersion] if the file uses a future schema
       def load_cpi(country)
         key = country.to_s.downcase
         code = country.to_s.upcase
         cpi_cache[[data_root, key]] ||= begin
-          raise UnsupportedCountry, code unless Supported::COUNTRIES.include?(code)
+          raise UnsupportedCountry, code unless Supported.country?(code)
 
           path = File.join(data_root, "cpi", "#{key}.json")
           unless File.exist?(path)
@@ -58,7 +74,7 @@ module Timeprice
 
       # Load the FX rates for a year.
       # @param year [Integer, String]
-      # @return [Hash] parsed JSON with a "rates" map of date → currency → Float
+      # @return [Hash] parsed JSON with `rates` (and optional `annual`) blocks
       # @raise [DataNotFound] if the per-year file is missing
       def load_fx_year(year)
         key = year.to_i
@@ -70,6 +86,17 @@ module Timeprice
         end
       end
 
+      # Load the sparse historical FX annual-only fallback file, if present.
+      # Returns nil when no fallback file ships with this data root.
+      # @return [Hash, nil]
+      def load_fx_annual_fallback
+        return @annual_fallback_cache[data_root] if @annual_fallback_cache&.key?(data_root)
+
+        @annual_fallback_cache ||= {}
+        path = File.join(data_root, "fx", "usd", "_annual.json")
+        @annual_fallback_cache[data_root] = File.exist?(path) ? parse_with_schema(path) : nil
+      end
+
       private
 
       def cpi_cache
@@ -80,6 +107,10 @@ module Timeprice
         @fx_cache ||= {}
       end
 
+      def manifest_cache
+        @manifest_cache ||= {}
+      end
+
       def parse_with_schema(path)
         data = JSON.parse(File.read(path))
         version = data["schema_version"]
@@ -90,3 +121,7 @@ module Timeprice
     end
   end
 end
+
+# Supported is loaded by the top-level entry point. Referenced lazily inside
+# load_cpi to avoid a require cycle (Supported reads the manifest via DataLoader).
+require_relative "supported" unless defined?(Timeprice::Supported)

data/lib/timeprice/errors.rb

@@ -7,23 +7,23 @@ module Timeprice
   # to handle anything the gem can throw at you.
   class Error < StandardError; end
 
-  # Raised when a country code is not in {Supported::COUNTRIES}.
+  # Raised when a country code is not in {Supported.countries}.
   class UnsupportedCountry < Error
     attr_reader :country
 
     def initialize(country)
       @country = country
-      super("Unsupported country: #{country.inspect} (supported: #{Supported::COUNTRIES.join(", ")})")
+      super("Unsupported country: #{country.inspect} (supported: #{Supported.countries.join(", ")})")
     end
   end
 
-  # Raised when a currency code is not in {Supported::CURRENCIES}.
+  # Raised when a currency code is not in {Supported.currencies}.
   class UnsupportedCurrency < Error
     attr_reader :currency
 
     def initialize(currency)
       @currency = currency
-      super("Unsupported currency: #{currency.inspect} (supported: #{Supported::CURRENCIES.join(", ")})")
+      super("Unsupported currency: #{currency.inspect} (supported: #{Supported.currencies.join(", ")})")
     end
   end
 

data/lib/timeprice/exchange.rb

@@ -33,8 +33,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.currency?(from)
+      raise UnsupportedCurrency, to   unless Supported.currency?(to)
 
       d = parse_date(date)
 
@@ -82,7 +82,7 @@ module Timeprice
     end
 
     # Walk back up to MAX_FALLBACK_DAYS to find a daily rate; if none, fall
-    # back to the year file's top-level `annual` block.
+    # back to data/fx/usd/_annual.json (the single source of annual FX truth).
     # Returns [rate, effective_date, granularity].
     def lookup_usd_base(currency, d)
       (0..MAX_FALLBACK_DAYS).each do |offset|
@@ -108,12 +108,12 @@ module Timeprice
       raise DataNotFound, "No FX rate for USD->#{currency} on or before #{d}"
     end
 
-    # Consult the year file's top-level `annual` block. Returns Float or nil.
+    # Consult data/fx/usd/_annual.json. Returns Float or nil.
     def annual_fallback(currency, year)
-      year_data = DataLoader.load_fx_year(year)
-      year_data.dig("annual", currency)&.to_f
-    rescue DataNotFound
-      nil
+      fallback = DataLoader.load_fx_annual_fallback
+      return nil unless fallback
+
+      fallback.dig("annual", year.to_s, currency)&.to_f
     end
 
     def parse_date(date)

data/lib/timeprice/inflation.rb

@@ -21,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
 
@@ -32,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

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/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.4.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.4.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

data/data/fx/usd/1983.json

@@ -1,11 +0,0 @@
-{
-  "schema_version": 2,
-  "base": "USD",
-  "year": 1983,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY (daily); World Bank PA.NUS.FCRF for VND (annual)",
-  "updated_at": "2026-05-11",
-  "rates": {},
-  "annual": {
-    "VND": 1.0
-  }
-}

data/data/fx/usd/1986.json

@@ -1,11 +0,0 @@
-{
-  "schema_version": 2,
-  "base": "USD",
-  "year": 1986,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY (daily); World Bank PA.NUS.FCRF for VND (annual)",
-  "updated_at": "2026-05-11",
-  "rates": {},
-  "annual": {
-    "VND": 22.94
-  }
-}

data/data/fx/usd/1987.json

@@ -1,11 +0,0 @@
-{
-  "schema_version": 2,
-  "base": "USD",
-  "year": 1987,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY (daily); World Bank PA.NUS.FCRF for VND (annual)",
-  "updated_at": "2026-05-11",
-  "rates": {},
-  "annual": {
-    "VND": 78.95
-  }
-}

data/data/fx/usd/1988.json

@@ -1,11 +0,0 @@
-{
-  "schema_version": 2,
-  "base": "USD",
-  "year": 1988,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY (daily); World Bank PA.NUS.FCRF for VND (annual)",
-  "updated_at": "2026-05-11",
-  "rates": {},
-  "annual": {
-    "VND": 611.65
-  }
-}

data/data/fx/usd/1989.json

@@ -1,11 +0,0 @@
-{
-  "schema_version": 2,
-  "base": "USD",
-  "year": 1989,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY (daily); World Bank PA.NUS.FCRF for VND (annual)",
-  "updated_at": "2026-05-11",
-  "rates": {},
-  "annual": {
-    "VND": 4501.69
-  }
-}

data/data/fx/usd/1990.json

@@ -1,11 +0,0 @@
-{
-  "schema_version": 2,
-  "base": "USD",
-  "year": 1990,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY (daily); World Bank PA.NUS.FCRF for VND (annual)",
-  "updated_at": "2026-05-11",
-  "rates": {},
-  "annual": {
-    "VND": 6537.6
-  }
-}

data/data/fx/usd/1991.json

@@ -1,11 +0,0 @@
-{
-  "schema_version": 2,
-  "base": "USD",
-  "year": 1991,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY (daily); World Bank PA.NUS.FCRF for VND (annual)",
-  "updated_at": "2026-05-11",
-  "rates": {},
-  "annual": {
-    "VND": 10121.89
-  }
-}

data/data/fx/usd/1992.json

@@ -1,11 +0,0 @@
-{
-  "schema_version": 2,
-  "base": "USD",
-  "year": 1992,
-  "source": "Frankfurter (ECB) for EUR/GBP/JPY (daily); World Bank PA.NUS.FCRF for VND (annual)",
-  "updated_at": "2026-05-11",
-  "rates": {},
-  "annual": {
-    "VND": 11202.19
-  }
-}