vehicles 0.9.0 → 0.9.2

data/lib/vehicles/model.rb

@@ -11,8 +11,10 @@ module Vehicles
   #   car.body_type   # => :hatchback
   #   car.suv?        # => false
   class Model
-    # Vehicle kinds (RDW `voertuigsoort`). Today the bundled data is all :car;
-    # the shape already supports the rest for when those packs land.
+    # Vehicle kinds the predicates know (`car?`, `van?`, …). The data itself
+    # publishes car, motorcycle, moped, van, truck and bus (Vehicles.kinds);
+    # pickup/trailer/quad/trike are kept so existing predicate calls answer
+    # false instead of raising.
     KINDS = %i[car motorcycle van truck pickup trailer bus moped quad trike].freeze
 
     # Body types — the sub-classification within a kind. For cars these are the
@@ -31,7 +33,7 @@ module Vehicles
     #   optional body_type/global_decile/availability/regions/aliases/forms/former_ids)
     # @param make [String] the parent make's display name
     # @param make_slug [String] the parent make's slug (for the composite slug)
-    def initialize(attrs, make:, make_slug:)
+    def initialize(attrs, make:, make_slug:) # rubocop:disable Metrics/AbcSize -- one line per published field
       @make       = make
       @make_slug  = make_slug
       @name       = attrs["name"]
@@ -74,9 +76,29 @@ module Vehicles
       # dataset 2026.10.1 (pipeline#255, ruling R3); nil on older snapshots
       # (including the bundled 2026.10.0) and for unranked records.
       @mass_decile = mass_decile_of(attrs)
+      # The first and last year this nameplate appears in official
+      # REGISTRATION data (dataset key `registration_years`), when published.
+      # Not production or model years: grey imports and late registrations
+      # widen it, and a register's coverage starts when its data does.
+      @registration_years = registration_years_of(attrs)
+      @id = id_of(make_slug)
       freeze
     end
 
+    # The canonical VehiclesDB id, "car/volkswagen/golf" (RESOLUTION.md §1):
+    # what to STORE. The same string the API, the SDKs and the widget use, and
+    # what Vehicles.by_id / Vehicles.identify read back — including after a
+    # dataset release renames the record (it lists the old id in former_ids).
+    attr_reader :id
+
+    # Years this nameplate shows up in official registrations, as
+    # `{ first: 1998, last: 2026 }` (the SDKs' shape), or nil when the dataset
+    # does not publish them.
+    # A HINT for ordering or pre-filling a year picker — never a validation
+    # bound: an import, a late registration or a register that starts in 2015
+    # all fall outside it legitimately. Not `years` (production years).
+    attr_reader :registration_years
+
     # "Volkswagen Golf" — the natural label for a model on its own.
     def full_name
       "#{make} #{name}"
@@ -154,20 +176,24 @@ module Vehicles
     def rare?    = rarity == :rare
 
     def to_h
-      { make: make, model: name, slug: slug, kind: kind, body_type: body_type,
+      { id: id, make: make, model: name, slug: slug, model_slug: model_slug, kind: kind, body_type: body_type,
         global_decile: global_decile, rarity: rarity,
-        availability: availability, regions: regions, aliases: aliases,
-        former_ids: former_ids, country_ranks: country_ranks, mass_decile: mass_decile }
+        availability: availability, regions: regions, aliases: aliases, forms: forms,
+        former_ids: former_ids, country_ranks: country_ranks, mass_decile: mass_decile,
+        registration_years: registration_years }
     end
 
-    # Value-object equality — two models with the same slug are equal.
+    # Value-object equality by canonical id (since 0.9.2). Until 0.9.1 it
+    # compared the composite slug, so the car and the van of one nameplate
+    # (Iveco Daily, Toyota Land Cruiser) were "equal" and collapsed in sets,
+    # `uniq` and hash keys.
     def ==(other)
-      other.is_a?(Model) && other.slug == slug
+      other.is_a?(Model) && other.id == id
     end
     alias eql? ==
 
     def hash
-      slug.hash
+      id.hash
     end
 
     def inspect
@@ -180,7 +206,10 @@ module Vehicles
     # They NEVER raise — a missing/slow API just yields nil and your view renders
     # a placeholder. See Vehicles::Providers.
 
-    # Production years as a Range, e.g. 1974..2024. nil without hosted data.
+    # Production years as a Range, e.g. 1974..2024. Honest status: neither
+    # the bundled data nor the hosted API publishes production years yet, so
+    # this answers nil today (the seam lights up when the API serves them).
+    # For a year-picker hint, see `registration_years`.
     def years
       Vehicles.resolve(:years, self)
     end
@@ -190,25 +219,43 @@ module Vehicles
       Vehicles.resolve(:segment, self)
     end
 
-    # One rendered image URL, ready for an <img src>. `size` picks the
+    # One image URL, ready for an <img src>. `size` picks the
     # variant (:sm/:md/:lg), `color` a palette slug (Vehicles.colors); an
-    # un-rendered color falls back honestly server-side rather than erroring.
-    # `year` is accepted for forward-compatibility but not yet served.
-    # nil without hosted data — always render a placeholder path.
-    def image(year: nil, color: nil, size: :md)
-      Vehicles.resolve(:image, self, year: year, color: color, size: size)
+    # unavailable color falls back honestly server-side (another color is
+    # served) unless `exact_color: true`, which answers nil instead. `year`
+    # is sent to the API, which rejects it until year-accurate images ship
+    # (→ nil; `images_result` says :invalid_request "unsupported_filter").
+    # nil without hosted data or on any failure — always render a
+    # placeholder path, and ask `images_result` when you need to know why.
+    def image(year: nil, color: nil, size: :md, exact_color: false)
+      Vehicles.resolve(:image, self, year: year, color: color, size: size, exact_color: exact_color)
     end
 
     # The full hosted images payload — every variant with dimensions, the
-    # rendered palette for this model, served-vs-requested color, provenance.
+    # available palette for this model, served-vs-requested color, provenance.
     # Reach for this when one URL isn't enough (srcset, color pickers,
     # caching whole responses). nil without hosted data.
-    def images(color: nil)
-      Vehicles.resolve(:images, self, color: color)
+    def images(color: nil, year: nil, exact_color: false)
+      Vehicles.resolve(:images, self, color: color, year: year, exact_color: exact_color)
+    end
+
+    # The same call as `images`, answering a Vehicles::HostedResult that says
+    # WHY when there is no image (no key, 401/402/429, not available, timeout…).
+    # Cached like `images`; never raises.
+    def images_result(color: nil, year: nil, exact_color: false)
+      Providers::HostedProvider.images_result(self, color: color, year: year, exact_color: exact_color)
     end
 
     private
 
+    def id_of(make_slug) = "#{@kind}/#{make_slug}/#{@model_slug}".freeze
+
+    def registration_years_of(attrs)
+      years = attrs["registration_years"]
+      first, last = years.is_a?(Hash) ? years.values_at("first", "last") : Array(years).first(2)
+      first.is_a?(Integer) && last.is_a?(Integer) && first <= last ? { first: first, last: last }.freeze : nil
+    end
+
     # The flat `mass_decile` key, or the nested `popularity.mass_decile` some
     # projections use.
     def mass_decile_of(attrs)

data/lib/vehicles/model_match.rb

@@ -46,9 +46,23 @@ module Vehicles
       model.nil?
     end
 
+    # Rungs that rest on curated data: safe to apply WITHOUT asking a human.
+    CONFIDENT_RUNGS = %i[exact former_id fold alias form cleaned].freeze
+
+    # Safe to auto-apply (e.g. canonicalize a stored make/model, or pre-fill a
+    # form without asking): an answer (not ambiguous) reached through curated
+    # data — the id, a former id, the name, a published alias, a curated
+    # registry form, or one of those after peeling an echoed make or a "new"
+    # filler. Not :fuzzy: a typo correction is a guess ("Clase" → "Classe")
+    # to SHOW the user ("did you mean…"), never to write silently.
+    # Equivalent to `!ambiguous? && confidence >= 0.9`.
+    def confident?
+      !ambiguous? && CONFIDENT_RUNGS.include?(rung)
+    end
+
     def to_h
-      { model: model&.to_h, method: rung.to_s, confidence: confidence, via: via,
-        candidates: candidates.map(&:to_h), ambiguous: ambiguous? }
+      { model: model&.to_h, id: model&.id, method: rung.to_s, confidence: confidence, via: via,
+        candidates: candidates.map(&:to_h), ambiguous: ambiguous?, confident: confident? }
     end
 
     def ==(other)

data/lib/vehicles/model_matcher.rb

@@ -44,12 +44,12 @@ module Vehicles
     module_function
 
     # The full ladder a–e. A ModelMatch, or nil when nothing matched at all.
-    def match(make_query, model_query, kind: nil)
+    def match(make_query, model_query, kind: nil, kinds: nil)
       make, via, make_typo = resolve_make(make_query)
       return nil unless make
 
-      via = kind_hint(kind) + via
-      ladder(make, model_query, kind, via, make_query: make_query, make_typo: make_typo)
+      ladder(make, model_query, KindRule.scope(kind, kinds), KindRule.via(kind, kinds) + via,
+             make_query: make_query, make_typo: make_typo)
     end
 
     # The model half of the ladder on a resolved make: a–c, then (for
@@ -69,8 +69,6 @@ module Vehicles
       heuristic(make, query, kind, via, make_query: make_query, make_typo: make_typo)
     end
 
-    def kind_hint(kind) = kind ? ["kind_hint:#{kind}"] : []
-
     # Rungs a–c only, on a resolved Make — what Vehicles.model answers. Rung a
     # is Make#model itself, so every pair that resolved before 0.9.0 resolves
     # identically; b–c are curated evidence, so on by default. A Model, or nil
@@ -189,9 +187,10 @@ module Vehicles
     def typo_hits(make, query, kind)
       limit = Fuzzy.budget(query.length)
       words = query.split
+      allowed = KindRule.symbols(kind)
       best = {}
       make.typo_keys.each do |key, model|
-        next if kind && model.kind != kind.to_sym
+        next unless KindRule.allows?(allowed, model)
         next if (key.length - query.length).abs > limit
         next unless (dist = word_distance(words, key, limit))
 
@@ -242,7 +241,7 @@ module Vehicles
       key = Vehicles.normalize(make_query)
       if (make = ds.find_make(make_query, fuzzy: false))
         own = key.empty? || key == Vehicles.normalize(make.name) || key == Vehicles.normalize(make.slug)
-        return [make, own ? [] : ["make_alias:#{key}→#{make.slug}"], false]
+        return [make, own ? [] : [ds.make_step(make, key)], false]
       end
       make = fuzzy ? ds.find_make(make_query, fuzzy: true) : nil
       make ? [make, ["make_typo:#{key}→#{make.slug}"], true] : [nil, [], false]

data/lib/vehicles/plates/series.rb

@@ -11,11 +11,16 @@ module Vehicles
       attr_reader :id, :klass, :categories, :period, :period_evidence,
         :pattern, :display_pattern, :regex, :regex_strict, :design,
         :variants, :sources, :notes, :validation_regexp, :lenient_regexp,
-        :issued_regexp, :issued_separators
+        :issued_regexp, :issued_separators, :matching, :recall_lenient_regexp,
+        :letters
 
       def initialize(entry)
         @id           = entry["id"]
         @klass        = entry["class"] || "standard"
+        # the plates spec §2.7 (normative): a series says whether a regex hit is a
+        # validity claim (`strict`) or only a shape hit (`recall-only`).
+        # Absent => strict, the spec's backward-compatible default.
+        @matching     = entry["matching"] || "strict"
         @categories   = Array(entry["categories"]).freeze
         @period       = (entry["period"] || {}).freeze
         @period_evidence = entry["period_evidence"]
@@ -25,6 +30,11 @@ module Vehicles
         @display_pattern = @pattern&.gsub(/\\(.)/) { $1 }
         @regex        = entry.dig("format", "regex")
         @regex_strict = entry.dig("format", "regex_strict")
+        # The letters this series issues, when the dataset enumerates them
+        # (es-national-2000: the 20 consonants). Nil when it does not; a few
+        # series carry prose there ("A-Z, no exclusions published"), not a set.
+        letters       = entry.dig("format", "charset", "letters")
+        @letters      = letters.is_a?(Array) ? letters.map(&:to_s).freeze : nil
         @design       = (entry["design"] || {}).freeze
         @variants     = Array(entry["variants"]).freeze
         @sources      = Array(entry["sources"]).freeze
@@ -32,18 +42,48 @@ module Vehicles
         # Compiled eagerly — the object is frozen, so no lazy memoization.
         @validation_regexp = compile(@regex_strict || @regex)
         @lenient_regexp    = compile(self.class.strip_separators(@regex_strict || @regex))
+        # The series' SHAPE without its issuing alphabet, only where the two
+        # differ (a `regex_strict` exists): what Match#near_misses tests.
+        @recall_lenient_regexp = @regex_strict && compile(self.class.strip_separators(@regex))
         segments, separators = self.class.segment_separators(@regex_strict || @regex)
         @issued_separators = (separators || []).freeze
         @issued_regexp = segments && compile("\\A(#{segments.join(')(')})\\z")
+        # The same segmentation with every quantifier lazy. When the greedy
+        # and lazy readings of a serial split it differently, the groups are
+        # not recoverable from the bare serial ("CD12345" is CD-123-45 or
+        # CD-1234-5): format_serial must not pick one.
+        @issued_lazy_regexp = segments && compile("\\A(#{segments.map { |seg| self.class.lazy(seg) }.join(')(')})\\z")
         freeze
       end
 
-      # A strict-validated series has an authority-alphabet regex twin; a
+      # A strict series' regex hit is a validity claim for that series; a
       # recall-only series (export/dark-blue catch-alls that accept any
-      # current shape) matches loosely by design. Consumers validating user
-      # input should weight strict hits above recall-only ones — Match does.
+      # current shape, the ES 1900-1971 numeric era) matches loosely by
+      # design. Read from the dataset's `matching:` key, never inferred from
+      # `regex_strict` being present: The plates spec §2.7 forbids that inference
+      # because most strict series need no strict twin (their `regex` already
+      # IS the issuing grammar — Portugal's AA-00-AA, the Spanish CD/CC/OI/TA
+      # series). Until 0.9.2 the gem inferred it, so 668 strict series
+      # (Portugal's whole national range among them) answered "not strict".
+      # Consumers validating user input should weight strict hits above
+      # recall-only ones — Match does.
       def strict?
-        !regex_strict.nil?
+        matching != "recall-only"
+      end
+
+      # Vehicle categories that carry people (dataset `categories`
+      # vocabulary). A series issued only to trailers, semitrailers,
+      # caravans, tractors, machines or trucks plates nothing a passenger
+      # rides in.
+      PASSENGER_CATEGORIES = %w[car van bus coach motorhome motorcycle moped scooter quadricycle tricycle
+                                ambulance].freeze
+
+      # Is this series issued to at least one passenger-carrying vehicle
+      # category? (es-national-2000: yes; es-trailer-1999 and the
+      # es-special-vehicles-1999 tractor plates: no.) Series without
+      # categories answer true: unknown is not "no".
+      def passenger?
+        categories.empty? || categories.intersect?(PASSENGER_CATEGORIES)
       end
 
       # period_evidence values on which the recorded START is not (or not
@@ -90,10 +130,15 @@ module Vehicles
       def format_serial(serial)
         return nil if serial.nil?
 
+        # A serial whose groups the series' own regex can split more than one
+        # way is returned as stored, before anything else: the bare serial
+        # cannot say which split was issued ("CD123456" is CD-123-456 or
+        # CD-12-3456; the dataset calls CD-999-999 representative), and a
+        # display pattern of one shape must not decide it.
+        return serial.dup.freeze if ambiguous_split?(serial)
+
         # The display pattern is authoritative when the serial fills it
-        # exactly — it knows splits the regex cannot (CC-999-999 over
-        # `\d+[- ]\d+` is ambiguous to a greedy match, unambiguous to the
-        # pattern).
+        # exactly and the regex has only one reading of it.
         slots = display_pattern&.each_char&.count { |ch| ![ "-", " ", "·", "." ].include?(ch) }
         if slots && serial.length == slots
           idx = 0
@@ -274,6 +319,40 @@ module Vehicles
         out.gsub(REDUNDANT_CHARACTER_CLASS_REPEAT) { "#{Regexp.last_match(1)}+" }
       end
 
+      # True when the greedy and lazy readings of the segmented regex split
+      # this serial differently.
+      def ambiguous_split?(serial)
+        greedy = issued_regexp&.match(serial) or return false
+        lazy = @issued_lazy_regexp&.match(serial) or return false
+        greedy.captures != lazy.captures
+      end
+
+      # A regex segment with its quantifiers made lazy (+ *, ?, {m,n}), for
+      # the ambiguity check in format_serial. Escapes and character classes
+      # are copied untouched.
+      def self.lazy(src)
+        out = +""
+        chars = src.chars
+        i = 0
+        while i < chars.size
+          ch = chars[i]
+          if ch == "\\"
+            out << ch << chars[i + 1].to_s
+            i += 2
+          elsif ch == "["
+            closing = i + 1
+            closing += 1 while closing < chars.size && chars[closing] != "]"
+            out << chars[i..closing].join
+            i = closing + 1
+          else
+            out << ch
+            out << "?" if [ "+", "*", "}" ].include?(ch) && chars[i + 1] != "?"
+            i += 1
+          end
+        end
+        out
+      end
+
       def inspect = %(#<Vehicles::Plates::Series #{id} "#{pattern}">)
 
       private

data/lib/vehicles/plates/template_fill.rb

@@ -6,14 +6,14 @@ module Vehicles
   module Plates
     # The REFERENCE FILLER for VehiclesDB plate templates — the client half of
     # the privacy-safe template endpoint
-    # (GET /plates/:code/:series_id/template.svg, VehiclesDB PRD-PLATE-ART §9).
+    # (GET /plates/:code/:series_id/template.svg, VehiclesDB plate-art spec §9).
     # A client downloads a template once (it carries nothing personal, so it
     # caches publicly) and writes the user's registration into it HERE, on its
     # own machine — a registration is personal data and never travels:
     #
     #   svg = Vehicles::Plates::TemplateFill.fill(template_svg, "1234 BCD")
     #
-    # Moved here from vehiclesdb-web (app/models/plates/template_fill.rb; same logic,
+    # Moved here from the VehiclesDB web app (app/models/plates/template_fill.rb; same logic,
     # plus shape_of and label:), whose renderer will call `fit_size` /
     # `recentered_baseline` from this gem
     # so the fit formula lives once. Deliberately dependency-free (Ruby stdlib

data/lib/vehicles/plates/templates.rb

@@ -3,7 +3,7 @@
 module Vehicles
   module Plates
     # VehiclesDB's real plate art for a registration, WITHOUT sending the
-    # registration anywhere (VehiclesDB PRD-PLATE-ART §9: a plate number is
+    # registration anywhere (VehiclesDB plate-art spec §9: a plate number is
     # personal data). The plate is fetched as a BLANK template — the series,
     # the registration's shape ("NNNN LLL", character classes only) and an
     # optional region — and filled locally by TemplateFill:
@@ -79,13 +79,17 @@ module Vehicles
       nil
     end
 
-    # The one series a match's plate is drawn as: the only standard-class
-    # series among the hits, else the only hit. Nil when it is ambiguous.
+    # The one series a match's plate is drawn as. Strict hits outrank
+    # recall-only ones (a Spanish "CD-123-456" is the diplomatic series, not
+    # the 1900-1971 numeric catch-all it also fits); among them, the only
+    # standard-class series, else the only hit. Nil when it is ambiguous.
     def template_series(found)
-      standard = found.series.select { |series| series.klass == "standard" }
+      strict = found.series.select(&:strict?)
+      candidates = strict.empty? ? found.series : strict
+      standard = candidates.select { |series| series.klass == "standard" }
       return standard.first if standard.one?
 
-      found.series.first if found.series.one?
+      candidates.first if candidates.one?
     end
 
     def fetch_template(code, series, shape, region)

data/lib/vehicles/plates.rb

@@ -3,7 +3,7 @@
 require "yaml"
 
 module Vehicles
-  # License-plate & registration-mark knowledge (the VehiclesDB PRD-PLATES
+  # License-plate & registration-mark knowledge (the VehiclesDB the plates spec
   # dataset, bundled offline like everything else in this gem). Ask it two
   # kinds of question:
   #
@@ -67,15 +67,20 @@ module Vehicles
       canon = typed.gsub(SEPARATORS, "")
       return Match.new(input: input.to_s, jurisdiction: juris, canon: canon, hits: []) if juris.nil? || canon.empty?
 
-      hits = juris.series.filter_map do |series|
-        next nil unless series.validation_regexp
+      hits = []
+      near_misses = []
+      juris.series.each do |series|
+        next unless series.validation_regexp
 
         exact = series.validation_regexp.match?(typed)
-        lenient = exact || series.lenient_regexp&.match?(canon)
-        Match::Hit.new(series: series, exact: exact) if lenient
+        if exact || series.lenient_regexp&.match?(canon)
+          hits << Match::Hit.new(series: series, exact: exact)
+        elsif series.recall_lenient_regexp&.match?(canon)
+          near_misses << series
+        end
       end
 
-      Match.new(input: input.to_s, jurisdiction: juris, canon: canon, hits: hits)
+      Match.new(input: input.to_s, jurisdiction: juris, canon: canon, hits: hits, near_misses: near_misses)
     end
 
     # The answer to "is this a plate, and which series issues it?".
@@ -84,12 +89,17 @@ module Vehicles
         def exact? = exact
       end
 
-      attr_reader :input, :jurisdiction, :canon, :hits
+      attr_reader :input, :jurisdiction, :canon, :hits, :near_misses
 
-      def initialize(input:, jurisdiction:, canon:, hits:)
+      def initialize(input:, jurisdiction:, canon:, hits:, near_misses: [])
         @input = input
         @jurisdiction = jurisdiction
         @canon = canon
+        # Series whose SHAPE the plate has but whose issuing ALPHABET it
+        # breaks: "1234 ABC" is the Spanish 2000 shape with vowels Spain never
+        # issues. Lets a form say WHY ("no vowels, Ñ or Q") instead of only
+        # "not a plate". Empty whenever the plate hits a strict series.
+        @near_misses = (hits.any? { |h| h.series.strict? } ? [] : near_misses).freeze
         # Exact hits outrank lenient ones, strict-validated series outrank
         # recall-only catch-alls; series order (standard first) breaks ties.
         @hits = hits.sort_by { |h| [ h.exact? ? 0 : 1, h.series.strict? ? 0 : 1 ] }.freeze
@@ -117,6 +127,42 @@ module Vehicles
       def suggestion
         formatted if valid? && !exact?
       end
+
+      # WHY the plate is (not) valid, as one Symbol — the same codes the
+      # VehiclesDB API answers (as strings):
+      #   :ok                   a strict series issues it (the authority's real alphabet)
+      #   :unverifiable         only a recall-only series has the shape (an era
+      #                         or catch-all whose alphabet is not published)
+      #   :excluded_letters     a series has this shape but never issues these
+      #                         letters ("1234 ABC": Spain issues no vowels, Ñ or Q)
+      #   :bad_shape            no series has this shape
+      #   :empty                nothing but separators was typed
+      #   :unknown_jurisdiction no plate data for that code
+      # Validity only: whether a passenger vehicle may carry it is `passenger?`.
+      def reason
+        return :unknown_jurisdiction if jurisdiction.nil?
+        return :empty if canon.empty?
+        return :ok if strict?
+        return :unverifiable if valid?
+
+        excluded_letters.empty? ? :bad_shape : :excluded_letters
+      end
+
+      # The letters of the plate that a near-miss series (same shape, an
+      # enumerated alphabet) never issues, e.g. ["A", "E"] for "1234 ABE" in
+      # Spain. [] when that is not why it failed.
+      def excluded_letters
+        letters = canon.scan(/[[:alpha:]]/).uniq
+        near_misses.select(&:letters).flat_map { |series| letters - series.letters }.uniq.sort
+      end
+
+      # Does a STRICT hit come from a series issued to passenger-carrying
+      # vehicles (Series#passenger?)? false for a valid trailer or tractor
+      # plate, and for anything not strictly valid. For apps that move
+      # people (ride sharing, rentals).
+      def passenger?
+        hits.any? { |hit| hit.series.strict? && hit.series.passenger? }
+      end
     end
   end
 end