timeprice 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 160a9501bc1004df45cd71202f3ae07711068adade2118cfe4605a2e92d92f6f
-  data.tar.gz: 68ea05103245f2bb1fb02d701fd5db6e1bb814a2b47d20f6eb9011d94a57b269
+  metadata.gz: a91644504f73e6324d522d189233539a5515ca51cf0be58b1a34da90ff78220d
+  data.tar.gz: f6120dc38bb433e1dc8ac56e523b3c547d9323b578f34a27bddee3e43b48c9a2
 SHA512:
-  metadata.gz: fdddfd9cbcf4cefad6ee73134eb8ef3e5ad5b863aa8d5a78fa789b8890cefec0690cf3c1022f1b596c2bdeaf6f9a8f1122d8ff6ef9adfb7dd393e0aa9346afb6
-  data.tar.gz: 4342d02e30f4058f6e7a98eedab2fd0fa54b14031f061bf4d17b093d02f6a1e5cd16ea1f994e7d868cc893fe29119bdae1a398724665f14502c9b135ee1396b0
+  metadata.gz: b8b0f99a9962bad944a02499761a586e860d50a3707e70de4d1549c6bf624ea5bf1a9d1d2beae488abdfc6646d825320259a196bfac177e64c25edab90e721e5
+  data.tar.gz: 54bb2545e7c9f9bbdb202994f3d5f53bb020a36bde0a2d8627c734a1c0e4312fcbe0237ce2b23409af9253ddc809ae74129dec43b17b94c559bcefa8917142cf

data/CHANGELOG.md

@@ -5,6 +5,88 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-05-11
+
+### Changed
+- **Schema v1 → v2.** Two structural data-layer changes, bundled under a
+  single bump:
+  - FX year files gain an optional top-level `annual` block. World Bank's
+    annual VND/USD average is stored there exactly once per year instead of
+    being broadcast across every daily date key. `Exchange.lookup_usd_base`
+    falls back from daily to annual when no daily entry exists within ±7
+    days and tags the result with `Granularity::ANNUAL`. `Compare` merges
+    FX granularity with CPI granularity (worst-precision wins).
+  - CPI provenance moves from a per-period map (`{"2025-01": "bls", ...}`)
+    to a compact range list (`[{series, from, to, provider}, ...]`). Single
+    -provider files (US/UK/EU/JP) collapse to 1–2 ranges; VN keeps the
+    WB→IMF transition explicit. ~42 kb saved across the 5 CPI files; one
+    real US data gap at 2025-10 is now visible instead of buried.
+- `country_file.rb` rebase label now preserves the original base reference
+  alongside the rebase date (e.g. `"2010=100 (rebased 2026-05-11)"`).
+
+### Added
+- Multi-source CPI chain for Vietnam: IMF Data Portal CPI dataflow
+  (`api.imf.org`, SDMX 2.1) is the monthly primary; World Bank `FP.CPI.TOTL`
+  remains as the annual fallback. The on-disk `data/cpi/vn.json` gains two
+  additive fields — `provenance` (per-period source id) and `providers`
+  (per-source status array) — so consumers can see which upstream supplied
+  each datapoint. Schema version is unchanged; old readers ignore the new
+  fields. Other country files (US, UK, EU, JP) gain the same fields on the
+  next refresh.
+- Internal: `Sources::Provider` / `Sources::CountryFile` / `Sources::MergePolicy`
+  seam for layering multiple providers into a single country file with
+  per-period provenance. Designed so future fresher sources (e.g. JP via
+  e-Stat) can be added as one more entry without further plumbing.
+
+## [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/DATA_LICENSES.md

@@ -12,7 +12,8 @@ string.
 | UK Office for National Statistics | `D7BT` (UK CPI all-items) | Open Government Licence v3.0 | https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/ | Contains public sector information licensed under the Open Government Licence v3.0 |
 | Eurostat | `prc_hicp_midx` (Euro area HICP) | Eurostat reuse policy — free reuse with source attribution | https://ec.europa.eu/eurostat/about-us/policies/copyright | Source: Eurostat |
 | World Bank | `FP.CPI.TOTL` (JP CPI fallback) | Creative Commons Attribution 4.0 International (CC BY 4.0) | https://datacatalog.worldbank.org/public-licenses#cc-by | Source: World Bank, FP.CPI.TOTL |
-| World Bank | `FP.CPI.TOTL` (VN CPI) | Creative Commons Attribution 4.0 International (CC BY 4.0) | https://datacatalog.worldbank.org/public-licenses#cc-by | Source: World Bank, FP.CPI.TOTL |
+| World Bank | `FP.CPI.TOTL` (VN CPI, annual fallback) | Creative Commons Attribution 4.0 International (CC BY 4.0) | https://datacatalog.worldbank.org/public-licenses#cc-by | Source: World Bank, FP.CPI.TOTL |
+| International Monetary Fund | CPI dataflow `VNM.CPI._T.IX.M` via IMF Data Portal (VN CPI, monthly primary) | Free reuse with attribution per IMF terms | https://www.imf.org/external/terms.htm | Source: IMF Data Portal CPI dataflow |
 | European Central Bank (via Frankfurter) | Daily reference rates, USD base, EUR/GBP/JPY | ECB reference rates — free reuse; Frankfurter is a non-commercial republisher with no separate license | https://www.ecb.europa.eu/services/disclaimer/html/index.en.html | FX data: European Central Bank reference rates via Frankfurter |
 | World Bank | `PA.NUS.FCRF` (VND annual average FX, broadcast daily) | Creative Commons Attribution 4.0 International (CC BY 4.0) | https://datacatalog.worldbank.org/public-licenses#cc-by | VND FX: World Bank, PA.NUS.FCRF |
 

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
@@ -89,7 +98,7 @@ Coverage is derived from the bundled `data/` files. Re-check with `timeprice sou
 | United Kingdom | GBP | ONS CPI all-items (`D7BT`) | Monthly + annual | 1988-01 → present |
 | Eurozone (EA) | EUR | Eurostat HICP (`prc_hicp_midx`) | Monthly + annual | 1996-01 → present |
 | Japan | JPY | World Bank `FP.CPI.TOTL` (fallback) | Annual | 1960 → 2024 |
-| Vietnam | VND | World Bank `FP.CPI.TOTL` | Annual | 1995 → 2024 |
+| Vietnam | VND | IMF Data Portal CPI dataflow (monthly primary) + World Bank `FP.CPI.TOTL` (annual fallback) | Monthly + annual | 1995 → present |
 
 **FX (USD base):** ECB reference rates via Frankfurter for **EUR / GBP / JPY**, daily
 1999 → present. **VND** uses the World Bank annual average (`PA.NUS.FCRF`) broadcast to
@@ -249,7 +258,7 @@ license — see `DATA_LICENSES.md` and `NOTICE` for the full table and license U
 - **UK CPI:** Contains public sector information licensed under the Open Government Licence v3.0.
 - **Eurozone HICP:** Source: Eurostat (reuse permitted with attribution).
 - **Japan CPI (fallback):** Source: World Bank, FP.CPI.TOTL (CC BY 4.0).
-- **Vietnam CPI:** Source: World Bank, FP.CPI.TOTL (CC BY 4.0).
+- **Vietnam CPI:** Sources: IMF Data Portal CPI dataflow (monthly primary); World Bank, FP.CPI.TOTL (annual fallback, CC BY 4.0).
 - **FX rates:** European Central Bank reference rates via Frankfurter.
 - **VND FX (annual broadcast):** World Bank, PA.NUS.FCRF (CC BY 4.0).
 

data/data/cpi/eu.json

@@ -395,7 +395,29 @@
     "2025-11": 129.33,
     "2025-12": 129.56
   },
-  "schema_version": 1,
+  "provenance": [
+    {
+      "series": "monthly",
+      "from": "1996-01",
+      "to": "2025-12",
+      "provider": "eurostat"
+    },
+    {
+      "series": "annual",
+      "from": "1996",
+      "to": "2025",
+      "provider": "eurostat"
+    }
+  ],
+  "providers": [
+    {
+      "fetched_at": "2026-05-11",
+      "id": "eurostat",
+      "label": "Eurostat prc_hicp_midx (HICP, EA all current members, CP00, 2015=100)",
+      "status": "ok"
+    }
+  ],
+  "schema_version": 2,
   "source": "Eurostat prc_hicp_midx (HICP, EA all current members, CP00, 2015=100)",
   "updated_at": "2026-05-11"
 }

data/data/cpi/jp.json

@@ -69,7 +69,23 @@
   "base_year": "2010=100",
   "country": "JP",
   "monthly": {},
-  "schema_version": 1,
-  "source": "World Bank FP.CPI.TOTL (annual)",
+  "provenance": [
+    {
+      "series": "annual",
+      "from": "1960",
+      "to": "2024",
+      "provider": "world_bank"
+    }
+  ],
+  "providers": [
+    {
+      "fetched_at": "2026-05-11",
+      "id": "world_bank",
+      "label": "World Bank FP.CPI.TOTL (annual, JP fallback)",
+      "status": "ok"
+    }
+  ],
+  "schema_version": 2,
+  "source": "World Bank FP.CPI.TOTL (annual, JP fallback)",
   "updated_at": "2026-05-11"
 }

data/data/cpi/uk.json

@@ -502,7 +502,29 @@
     "2026-02": 140.1,
     "2026-03": 141.0
   },
-  "schema_version": 1,
+  "provenance": [
+    {
+      "series": "monthly",
+      "from": "1988-01",
+      "to": "2026-03",
+      "provider": "ons"
+    },
+    {
+      "series": "annual",
+      "from": "1988",
+      "to": "2025",
+      "provider": "ons"
+    }
+  ],
+  "providers": [
+    {
+      "fetched_at": "2026-05-11",
+      "id": "ons",
+      "label": "ONS D7BT — UK CPI all-items index (2015=100)",
+      "status": "ok"
+    }
+  ],
+  "schema_version": 2,
   "source": "ONS D7BT — UK CPI all-items index (2015=100)",
   "updated_at": "2026-05-11"
 }

data/data/cpi/us.json

@@ -474,7 +474,35 @@
     "2026-02": 326.785,
     "2026-03": 330.213
   },
-  "schema_version": 1,
+  "provenance": [
+    {
+      "series": "monthly",
+      "from": "1990-01",
+      "to": "2025-09",
+      "provider": "bls"
+    },
+    {
+      "series": "monthly",
+      "from": "2025-11",
+      "to": "2026-03",
+      "provider": "bls"
+    },
+    {
+      "series": "annual",
+      "from": "1990",
+      "to": "2024",
+      "provider": "bls"
+    }
+  ],
+  "providers": [
+    {
+      "fetched_at": "2026-05-11",
+      "id": "bls",
+      "label": "BLS CUUR0000SA0 (CPI-U, U.S. city average, all items)",
+      "status": "ok"
+    }
+  ],
+  "schema_version": 2,
   "source": "BLS CUUR0000SA0 (CPI-U, U.S. city average, all items)",
   "updated_at": "2026-05-11"
 }