vehicles 0.9.0 → 0.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad4bfedaec8a545537a02ae2952769d89ebe8fda56a3643687030af44482009e
-  data.tar.gz: 19589e34b13ea5ce0a31e06482378a5324f4b9b3897f91c31e72375d9b5639a5
+  metadata.gz: aa213b02a603746bbd7c6bfca44ca4dd68b4d22a24d82fdf2a4e4742447f0d70
+  data.tar.gz: b1cf8cddd58344ec2bc8bc780619103f4b4f0374f34472595a48531247022d8f
 SHA512:
-  metadata.gz: d26f0e4edf6cbe436184469c069dacc6df746aa77241acecfe5cf77cbd4dc88d48b1d3d084cf2bdddf02fa32709c39b72eaba7f0fc6f4a7254e1e08ee7b5a6ad
-  data.tar.gz: e1ddc6f6bcc52f4b08e1377bae670e97ecf4e4dd9937712c685c73c28813df3c8a910b90459ec8ebe9b09eafe3d16255380cfe8155146d2c07db0003c9c0a8a7
+  metadata.gz: c02046f4ca89a6abbcdb7666db048bd28650960e28d4f41c277d0dba9efd4ef1489abf2534e80fb7d7be21b3451d824cc5150cc1c77145b47b26b9b4b36aecab
+  data.tar.gz: 0c9bebfcb0fe391fdb1119a071aa019495283ca056be8a4ad94632d88a407b5318cb5289de6d2126b672ca3bf2c461f47fe466e6a81b9a5ecef97aa67a07d0e2

data/CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.2] - 2026-11-10
+
+Everything below the plates fixes comes from dogfooding the gem in a production Rails app (CarHey) and making each workaround it had to write a general feature.
+
+### Upgrade notes
+- **Car-only apps: pass `kind: :car` (or `kinds: [:car]`) when you canonicalize.** Without a kind the collision rule now answers the most-registered kind, so `match_model("Volkswagen", "Caddy")` is `van/volkswagen/caddy` (Berlingo, Transit, Hilux… likewise). Stored ids are unaffected; only what an unhinted string means changes. CarHey: `Vehicle.canonical_identity` must call `Vehicles.match_model(make, model, kind: :car)`.
+- `refresh!` now refuses releases it used to accept; check `Vehicles.refresh.reason` if your data stops moving.
+- `Model#==` compares ids: code that relied on a car and a van "being equal" (Set/uniq/hash keys) now keeps both.
+
+### Changed (behaviour)
+- **One kind-collision rule, shared by every VehiclesDB surface** (`Vehicles::KindRule`; vehiclesdb RESOLUTION.md §3). When one nameplate is several records (Iveco "Daily" is a van, a truck and a bus) and no kind is given, `Vehicles.model`, `Make#model`, `match_model` and `identify` pick the lowest `mass_decile`, then van → car → bus → truck → moped → motorcycle, then the id. Until 0.9.1 the gem preferred the car (else file order) while the SDKs used another tie-break, so the stored id depended on the door a user came through. Backtested on register counts, the rule picks the most-registered kind in 87% of collision groups (car-first: 43%). Pass `kind:` to keep a kind.
+- **`Model#==`, `eql?` and `hash` compare the canonical id**, not the composite slug: the car and the van of one nameplate are no longer equal (they used to collapse in sets, `uniq` and hash keys).
+- `Vehicles.refresh!` keeps returning true/false, but now true means "the app has the latest release" (written, or already current), and it refuses releases it used to accept (see Safe refresh).
+- `Model#image(year:)` sends `year` to the API instead of silently dropping it; the API answers `422 unsupported_filter` until year-accurate images ship, so `image(year:)` is nil and `images_result` says why.
+- A refreshed cache older than the gem's bundled data, or in a schema the gem does not read, is no longer served.
+- `Model#to_h` gains `id`, `model_slug`, `forms`, `registration_years`; `ModelMatch#to_h` gains `id` and `confident`.
+
+### Added
+- **Safe refresh.** `Vehicles.refresh` returns a `Vehicles::RefreshResult` (`status` :updated/:current/:rejected/:failed, `reason`, `version`, `previous_version`, `message`; never raises). It reads the release manifest first (`config.manifest_url`, derived from `data_url`): an unsupported schema or an older version is refused and the same version downloads nothing. The payload is fetched from the announced release (jsDelivr `@latest` pinned to it), must carry that version and schema, match the manifest's per-kind model counts and its sha256 when published, keep every kind and (kind, country) slice at or above `config.refresh_min_ratio` (0.9) of the data in use, and pass the optional `config.refresh_guard`. Written atomically.
+- **Every process adopts a new dataset on its own**: at most every `config.reload_check_interval` seconds (default 5) a call stats the file and reloads when it changed — no restart, no executor hook. A corrupt file never replaces the dataset in memory. `config.cache_dir` (or `VEHICLES_CACHE_DIR`) puts the cache on a shared volume, so one refresh reaches every container. README: "Staying current" has the multi-container recipe.
+- **Canonical ids**: `Model#id` (`"car/volkswagen/golf"`), `Vehicles.by_id(id, follow: true)` (follows `former_ids`; a split id answers nil), `Vehicles.successor(id)` (the id to store now), `Vehicles.live?(id)`. Make `former_slugs` are read when the dataset publishes them (`Make#former_slugs`, `Vehicles.make("old-slug")`, `by_id` across a make rename); a no-op until then.
+- **`kinds:`** on `Vehicles.model`, `match_model`, `identify`, `by_id`, `catalog` and `Make#model`: a hard filter on every rung, ids included (`identify("bus/iveco/daily", kinds: [:car])` → nil). `kind:` keeps scoping the name rungs and never overrides an explicit id.
+- **`ModelMatch#confident?`**: an answer from a curated rung (exact, former_id, fold, alias, form, cleaned), never fuzzy or ambiguous — the recommended threshold for writing a match back without asking.
+- **Per-country catalog**: `country:` on `Vehicles.catalog`, `makes`, `models`, `make_options` and `model_options` (models with official evidence there, in that country's own order). `top_models(limit: nil)` returns every match.
+- **Labels in English and Spanish** (the same strings as the JS/Python SDKs): `Vehicles.colors(locale: :es)`, `Vehicles.color_options(locale: :es)`, `Color#label(:es)`, `Vehicles.kind_label` / `kind_options`, `Vehicles.body_type_label` / `body_type_options`. `Vehicles.color` resolves Spanish input ("Rojo", "marrón", "plateada", "granate"). English labels for `wagon`/`coupe` read "Wagon"/"Coupe".
+- **Hosted errors are no longer silent**: `Model#images_result` returns a `Vehicles::HostedResult` (`reason`, `status`, the API's own `error` code, `url(size)`); `config.on_hosted_error` and a warn log line fire for 401/402/403/429/5xx/timeouts (never for a missing image). Image payloads are cached (`config.image_cache`, in-process by default; `image_cache_ttl` 1 day capped by the payload's `expires_at`, `image_miss_ttl` 10 min for 404s; errors never cached). `exact_color: true` answers nil instead of another color's image and remembers the palette so an unavailable color costs no request. ActiveSupport notifications `request.vehicles` / `refresh.vehicles` when present.
+- **`Vehicles.dataset_slice(kind:, kinds:, country:, region:)`**: the `catalog` scope as records in the shape of the published `dist/vehicles.json` (a Hash, ready for `to_json`): make and model slugs, kinds, aliases, forms, former ids, availability, deciles, country ranks and registration years, plus the release's version and CC-BY attribution. It is what the make-model-dropdown widget's `data` option (0.4.1) and the JS/Python SDKs' dataset mode read, so a page can embed its scope and resolve stored values and canonical ids with no CDN or API request. Lean: no `regions` or `body_type`, and with `country:` the per-country fields keep only that country (Spain's cars on data 2026.11.3: ~360 KB of JSON, ~57 KB gzipped). README: a Rails recipe that embeds it.
+- `Model#registration_years`: `{ first:, last: }` — the first and last year in official registrations, when the dataset publishes it (dataset 2026.11.3 publishes it for ~9,900 of 16,032 records). A hint, never a validation bound; `Model#years` docs now say plainly that production years are not published yet.
+- Plates: `Match#reason` (`:ok`, `:unverifiable`, `:excluded_letters`, `:bad_shape`, `:empty`, `:unknown_jurisdiction` — the API's codes), `Match#excluded_letters`, `Match#passenger?` and `Series#passenger?` (issued to passenger-carrying vehicles; trailer and tractor series are not).
+- Validators take `kind:`, `kinds:` and `country:` (`vehicle_make: { kind: :car, country: :es }`).
+- `Plates::Match#near_misses`: the series whose shape a plate has but whose issuing alphabet it breaks ("1234 ABC" → `es-national-2000`: Spain issues no vowels, Ñ or Q). Empty whenever the plate hits a strict series. Lets a form explain the rejection. `Series#matching` and `Series#recall_lenient_regexp` back it, and `Series#letters` (the issued letter set, when the dataset enumerates one) tells a form whether the alphabet is what failed.
+
+### Fixed
+- The hosted client follows a former id's `301` (same origin only, so the key never leaves the host): images no longer vanish around a rename or a gem/API version skew.
+- `Vehicles.regions` follows the dataset in effect (it was memoized once per process).
+- Docs: the "car catalog is tens of KB" claim (it is ~63 KB worldwide, ~14 KB for one country), `Model::KINDS` ("all :car"), and the initializer's "EU market" text.
+- **`Plates::Series#strict?` now reads the dataset's `matching:` key** (the plates spec §2.7, normative) instead of inferring strictness from a `regex_strict` twin being present. The spec forbids that inference: most strict series need no twin because their `regex` already is the issuing grammar. 668 strict series were answering `strict? == false` before, among them Portugal's whole national range (AA-00-AA) and the Spanish CD/CC/OI/TA, military and police series. `Match#strict?` follows. Found by dogfooding: 2 of CarHey's 3 Portuguese cars validated as "recall-only".
+- `Match#formatted` / `Series#format_serial` no longer invent a split when the series' regex can split a serial more than one way (`Series#ambiguous_split?`): "CD12345" and "CD123456" come back as stored instead of "CD-1234-5" / the representative "CD-123-456". This runs before the display-pattern walk; 22 series with variable-width groups (ES diplomatic, personalised and special-index plates) are affected.
+- `Plates.template_series` (what `Plates.render` draws) prefers strict hits over recall-only ones: a Spanish "CD-123-456" is drawn as the diplomatic series, not as the 1900–1971 numeric catch-all it also fits.
+
+### Changed
+- Bundled data refreshed to VehiclesDB v2026.11.6 (16,327 models) and its conformance file from vehiclesdb main (with the vehiclesdb#397 kind-collision cases and the corrected E-Klasse case). Since 2026.11.3 the dataset is the first release to publish make `former_slugs` (`Vehicles.make("renault-alpine")` is Alpine, `by_id("car/renault-alpine/a110")` follows it), model `registration_years` and per-file `sha256`/`bytes` in the manifest's `dist_files`, which `Vehicles.refresh` now verifies on real releases. The gem's readers already used the shipped names.
+- v2026.11.2, bundled earlier in this cycle, restyled names such as "León", "XCeed", "ProCeed".
+- Bundled plates corpus refreshed to vehiclesdb `db0ec0a`: adds Egypt, Nigeria and Türkiye (127 jurisdictions, 1,409 series) and the Andorra and Austria verification corrections.
+
+## [0.9.1] - 2026-11-09
+
+### Changed
+- Bundled data refreshed to VehiclesDB v2026.11.1: 15,635 models. Passenger versions of van-based MPVs now also publish in kind `car` (Caddy, Berlingo, Kangoo, Rifter, Tourneo Custom/Courier/Connect, Transit Custom, Doblò and more), plus the VW Multivan, GWM Ora 5, Ebro S800/S900, the Alfa Romeo 6C/8C classics and 24 typo-twin folds. Every retired id resolves through `former_ids`. Spanish new-car registrations landing on a published record go from 90.2% to 96.5%.
+
 ## [0.9.0] - 2026-11-09
 
 ### Changed
@@ -118,7 +168,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   template per window, not one per call. Keys carry the template schema and
   gem version.
 - `Vehicles::Plates::TemplateFill`: the reference filler, moved verbatim from
-  vehiclesdb-web (`fill`, `metadata`, `groups`, and the shared fit formulas
+  the VehiclesDB web app (`fill`, `metadata`, `groups`, and the shared fit formulas
   `fit_size` / `recentered_baseline` the VehiclesDB renderer will call from
   here), plus `shape_of` and a `label:` option for a localized accessible
   name. Standard library only; the file loads on its own in a gem-less Ruby.
@@ -264,7 +314,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- Plates dataset refreshed — the overnight swarm passes' settlements
+- Plates dataset refreshed — the overnight verification passes' settlements
   land: the Cypriot centre date mark, Brazil's square-dot printed form
   and photographed moto split, San Marino's structured legend/sigla
   fields, Ukraine's statutory line counts, California's pixel-sampled
@@ -381,7 +431,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.6.0] - 2026-07-27
 
-License plates become a first-class citizen: the PRD-PLATES registration-mark
+License plates become a first-class citizen: the VehiclesDB registration-mark
 dataset ships in the gem, bundled and offline like everything else.
 
 ### Added
@@ -401,20 +451,20 @@ The hosted images API is **live** — this release points the wired-up provider
 seam at the real thing.
 
 ### Added
-- `Model#image(color:, size:)` returns a rendered variant URL from the live
+- `Model#image(color:, size:)` returns an image variant URL from the live
   VehiclesDB images API (`:sm` 320×180, `:md` 640×360, `:lg` 1280×720, webp).
   Mint a key at <https://vehiclesdb.com/settings/api-keys> and set
   `config.api_key`; without a key it stays nil, as always.
 - `Model#images(color:)` returns the full payload: every variant with
-  dimensions, the rendered palette for the model, served-vs-requested color
-  (un-rendered colors fall back honestly instead of 404ing), provenance.
+  dimensions, the available palette for the model, served-vs-requested color
+  (unavailable colors fall back honestly instead of 404ing), provenance.
 
 ### Changed
 - `config.api_base_url` default is now `https://vehiclesdb.com` (the live API
   origin; endpoint paths carry `/v1`). It must be an ORIGIN — no path suffix.
 - `Model#image` accepts `year:` but does not send it: `year`/`trim` are
   reserved filters server-side (the API 422s on them by contract) until
-  year-accurate renders ship.
+  year-accurate images ship.
 
 ## [0.4.1] - 2026-07-26