vehicles 0.4.1 → 0.6.1

data/lib/vehicles/plates/series.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Vehicles
+  module Plates
+    # One registration series: a pattern identity with a period, a class
+    # (standard/taxi/diplomatic/…), categories, sourced design facts, and the
+    # two regexes of the dataset's regex policy — `regex` (recall: the
+    # pattern's own alphabet) and `regex_strict` (validation: the alphabet
+    # the authority actually issues). Validation prefers strict.
+    class Series
+      attr_reader :id, :klass, :categories, :period, :pattern, :regex,
+        :regex_strict, :design, :variants, :sources, :notes,
+        :validation_regexp, :lenient_regexp
+
+      def initialize(entry)
+        @id           = entry["id"]
+        @klass        = entry["class"] || "standard"
+        @categories   = Array(entry["categories"]).freeze
+        @period       = (entry["period"] || {}).freeze
+        @pattern      = entry.dig("format", "pattern")
+        @regex        = entry.dig("format", "regex")
+        @regex_strict = entry.dig("format", "regex_strict")
+        @design       = (entry["design"] || {}).freeze
+        @variants     = Array(entry["variants"]).freeze
+        @sources      = Array(entry["sources"]).freeze
+        @notes        = entry["notes"]
+        # 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))
+        freeze
+      end
+
+      # A strict-validated series has an authority-alphabet regex twin; 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.
+      def strict?
+        !regex_strict.nil?
+      end
+
+      # "2000 →" (open, runs until exhausted) or "1971–2000".
+      def period_label
+        finish = period["end"]
+        finish ? "#{period["start"]}–#{finish}" : "#{period["start"]} →"
+      end
+
+      # Re-print a separator-less serial the way this series formats it:
+      # walk the pattern; 9/L and literal serial characters consume one input
+      # character, separator characters re-emerge from the pattern itself.
+      def format_serial(serial)
+        return nil if serial.nil? || pattern.nil?
+
+        idx = 0
+        out = pattern.each_char.with_object(+"") do |ch, str|
+          if [ "-", " ", "·", "." ].include?(ch)
+            str << ch
+          else
+            str << (serial[idx] || "")
+            idx += 1
+          end
+        end
+        out.freeze
+      end
+
+      # Tokens that read as "a separator" when they make up a whole
+      # character class — `[- ]` in the ES consular series is dash-or-space,
+      # i.e. a separator spelled as a class.
+      SEPARATOR_TOKENS = [ " ", "-", "·", ".", '\s', '\-', '\.', '\ ' ].freeze
+
+      # Remove separator LITERALS from a regex source, respecting character
+      # classes (the "-" inside [A-Z] is a range, not a separator; a class
+      # composed ONLY of separators, like `[- ]`, is a separator and goes).
+      # A quantifier left dangling by a removed separator ("-?", "[- ]?") is
+      # swallowed with it. Linear scan — regexes in this dataset are simple.
+      def self.strip_separators(src)
+        return nil if src.nil?
+
+        out = +""
+        chars = src.chars
+        i = 0
+        while i < chars.size
+          ch = chars[i]
+
+          if ch == "\\" && i + 1 < chars.size
+            nxt = chars[i + 1]
+            if [ "s", "-", ".", " " ].include?(nxt)
+              i += 2
+              i += 1 if [ "?", "*" ].include?(chars[i]) # optional separator: drop its quantifier too
+            else
+              out << ch << nxt
+              i += 2
+            end
+            next
+          end
+
+          if ch == "["
+            # Copy or drop the WHOLE class span in one decision.
+            closing = i + 1
+            closing += 1 while closing < chars.size && chars[closing] != "]"
+            content = chars[(i + 1)...closing].join
+            tokens = content.scan(/\\.|./m)
+            if tokens.any? && tokens.all? { |t| SEPARATOR_TOKENS.include?(t) }
+              i = closing + 1
+              i += 1 if [ "?", "*" ].include?(chars[i])
+            else
+              out << chars[i..closing].join
+              i = closing + 1
+            end
+            next
+          end
+
+          if [ "-", " ", "·" ].include?(ch)
+            i += 1
+            i += 1 if [ "?", "*" ].include?(chars[i])
+          else
+            out << ch
+            i += 1
+          end
+        end
+        out
+      end
+
+      def inspect = %(#<Vehicles::Plates::Series #{id} "#{pattern}">)
+
+      private
+
+      # Bad regex in data must degrade like every other lookup: nil, not raise.
+      def compile(source)
+        return nil if source.nil?
+
+        Regexp.new(source)
+      rescue RegexpError
+        nil
+      end
+    end
+  end
+end

data/lib/vehicles/plates.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Vehicles
+  # License-plate & registration-mark knowledge (the VehiclesDB PRD-PLATES
+  # dataset, bundled offline like everything else in this gem). Ask it two
+  # kinds of question:
+  #
+  #   Vehicles.plates                 # => every Jurisdiction
+  #   Vehicles.plates(:nl)            # => one Jurisdiction (series, charset, authority)
+  #   Vehicles.plate("12-GB-BD", jurisdiction: :nl)   # => Plates::Match
+  #
+  # Matching is TWO-TIER, because humans type plates every way at once:
+  #
+  #   exact   — the input, upcased, matches a series' STRICT regex as-typed
+  #             (separators included): formatted exactly as issued.
+  #   lenient — the input with separators stripped ("1234XYZ", "1234 xyz",
+  #             "1234-XYZ" all collapse to "1234XYZ") matches the same strict
+  #             alphabet with the separators removed. Still the authority's
+  #             real issuing alphabet — only the punctuation is forgiven.
+  #
+  # A lenient-only match carries `suggestion`: the serial re-formatted the
+  # way it appears on the physical plate ("did you mean 1234 XYZ").
+  # Same posture as every lookup in this gem: garbage in => empty result,
+  # never an exception.
+  module Plates
+    DATA_DIR = File.expand_path("../../data/plates", __dir__)
+
+    # What people type between plate groups: space(s), hyphen/en/em dash,
+    # middot, period. Stripped for the lenient tier (and from the strict
+    # regexes to derive their lenient twins).
+    SEPARATORS = /[\s\-–—·.]+/
+
+    module_function
+
+    def jurisdictions
+      @jurisdictions ||= Dir.glob(File.join(DATA_DIR, "*.yml")).sort.map do |path|
+        Jurisdiction.load(path)
+      end
+    end
+
+    def jurisdiction(code)
+      jurisdictions.find { |j| j.code == code.to_s.downcase.tr("_", "-") }
+    end
+
+    def classes
+      @classes ||= YAML.safe_load_file(File.join(DATA_DIR, "_meta", "classes.yml")) || {}
+    end
+
+    # The matcher behind Vehicles.plate. Unknown jurisdiction => empty Match.
+    def match(input, jurisdiction:)
+      juris = jurisdiction(jurisdiction)
+      typed = input.to_s.upcase.strip
+      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
+
+        exact = series.validation_regexp.match?(typed)
+        lenient = exact || series.lenient_regexp&.match?(canon)
+        Match::Hit.new(series: series, exact: exact) if lenient
+      end
+
+      Match.new(input: input.to_s, jurisdiction: juris, canon: canon, hits: hits)
+    end
+
+    # The answer to "is this a plate, and which series issues it?".
+    class Match
+      Hit = Struct.new(:series, :exact, keyword_init: true) do
+        def exact? = exact
+      end
+
+      attr_reader :input, :jurisdiction, :canon, :hits
+
+      def initialize(input:, jurisdiction:, canon:, hits:)
+        @input = input
+        @jurisdiction = jurisdiction
+        @canon = canon
+        # 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
+        freeze
+      end
+
+      def valid? = hits.any?
+      def exact? = hits.any?(&:exact?)
+
+      # True when at least one hit is a strict-validated series — the strong
+      # signal ("the authority issues this alphabet"), vs a catch-all shape
+      # union like an export plate. Prefer this for user-input validation.
+      def strict? = hits.any? { |h| h.series.strict? }
+
+      def series = hits.map(&:series)
+      def best = hits.first&.series
+
+      # The serial formatted the way the best-matching series prints it on
+      # the physical plate — "1234XYZ" typed, "1234 XYZ" issued.
+      def formatted
+        best&.format_serial(canon)
+      end
+
+      # Only when the user's punctuation was off: the "did you mean" string.
+      def suggestion
+        formatted if valid? && !exact?
+      end
+    end
+  end
+end

data/lib/vehicles/providers/hosted_provider.rb

@@ -11,10 +11,11 @@ module Vehicles
     # resolver falls back to the local data. Tracking/enrichment must never break
     # the host app, so this never raises out.
     #
-    # NOTE: the public VehiclesDB API is not live yet. This is the wired-up seam:
-    # the moment the service ships (and you set `config.api_key`), these methods
-    # light up with zero code changes on the consumer's side. Until then they
-    # safely return nil. Endpoint shape is provisional — see https://vehiclesdb.com.
+    # The images endpoint is LIVE (since 2026-07): mint a key at
+    # https://vehiclesdb.com/settings/api-keys, set `config.api_key`, and
+    # `model.image` / `model.images` answer with rendered vehicle imagery.
+    # The enrichment endpoints (years/segment) are still the wired-up seam —
+    # they safely return nil until the service ships them.
     module HostedProvider
       module_function
 
@@ -33,11 +34,28 @@ module Vehicles
         fetch(model)&.dig("segment")&.to_sym
       end
 
-      def image(model, year:, color:)
+      # One variant URL — the common "just give me an <img src>" case.
+      # `size` picks from the API's rendered variants (:sm 320×180, :md
+      # 640×360, :lg 1280×720; webp).
+      def image(model, year: nil, color: nil, size: :md)
+        images(model, color: color)&.dig("variants", size.to_s, "url")
+      end
+
+      # The full images payload for a model — palette, every variant with
+      # dimensions, provenance, and the honest color fallback: `color` is what
+      # the API actually served, `requested_color` what you asked for (a color
+      # that isn't rendered yet falls back rather than 404ing).
+      #
+      # GET /v1/vehicles/:kind/:make_slug/:model_slug/images?color=<slug>
+      #
+      # `year`/`trim` filters are RESERVED server-side today (the API 422s on
+      # them by contract, so callers can't silently build on unimplemented
+      # semantics) — which is why `image` accepts `year:` but never sends it:
+      # serving the current rendering beats an error until the filter ships.
+      def images(model, color: nil)
         params = {}
-        params[:year]  = year  if year
-        params[:color] = color if color
-        get("/v1/models/#{model.slug}/image", params)&.dig("url")
+        params[:color] = color.to_s unless color.to_s.empty?
+        get("/v1/vehicles/#{model.kind}/#{model.make_slug}/#{model.model_slug}/images", params)
       end
 
       # --- internals -----------------------------------------------------------

data/lib/vehicles/providers/local_provider.rb

@@ -17,9 +17,10 @@ module Vehicles
       # The bundled snapshot is make/model/kind/body_type only — richer fields
       # come from the hosted API. Returning nil here lets the resolver move on
       # (and ultimately yield nil) instead of raising.
-      def years(_model)               = nil
-      def segment(_model)             = nil
-      def image(_model, year:, color:) = nil
+      def years(_model)                                          = nil
+      def segment(_model)                                        = nil
+      def image(_model, year: nil, color: nil, size: :md)        = nil
+      def images(_model, color: nil)                             = nil
     end
   end
 end

data/lib/vehicles/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vehicles
-  VERSION = "0.4.1"
+  VERSION = "0.6.1"
 end

data/lib/vehicles.rb

@@ -10,6 +10,9 @@ require_relative "vehicles/refresher"
 require_relative "vehicles/providers/local_provider"
 require_relative "vehicles/providers/hosted_provider"
 require_relative "vehicles/other_option"
+require_relative "vehicles/plates"
+require_relative "vehicles/plates/jurisdiction"
+require_relative "vehicles/plates/series"
 
 # Car makes & models for your Rails app — dropdowns, search, validation. Bundled
 # data, zero config, no network calls. Standalone first; an SDK for the hosted
@@ -135,6 +138,24 @@ module Vehicles
       found&.model(model_name)
     end
 
+    # License plates (the bundled PRD-PLATES dataset). No argument: every
+    # jurisdiction. With a code: that jurisdiction (or nil — forgiving).
+    #   Vehicles.plates          # => [#<Jurisdiction nl …>, …]
+    #   Vehicles.plates(:nl)     # => the Netherlands entry (33 series)
+    def plates(code = nil)
+      code.nil? ? Plates.jurisdictions : Plates.jurisdiction(code)
+    end
+
+    # Validate a typed registration against a jurisdiction's real series.
+    # Two-tier: exact as-issued, else separator-forgiving with a formatting
+    # suggestion. Never raises; unknown jurisdictions yield an empty match.
+    #   Vehicles.plate("12-GB-BD", jurisdiction: :nl).valid?     # => true (exact)
+    #   Vehicles.plate("1234XYZ", jurisdiction: :es).suggestion  # => "1234 XYZ"
+    #   Vehicles.plate("12-AB-CD", jurisdiction: :nl).valid?     # => false (vowel purge)
+    def plate(input, jurisdiction:)
+      Plates.match(input, jurisdiction: jurisdiction)
+    end
+
     # Every model matching a query, ranked. => [Vehicles::Model, ...]
     def search(query)
       dataset.search(query)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: vehicles
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.6.1
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-07-26 00:00:00.000000000 Z
+date: 2026-08-01 00:00:00.000000000 Z
 dependencies: []
 description: vehicles ships a curated, bundled dataset of car makes and models (with
   kind and body type) and a delightful, Rails-friendly API for vehicle dropdowns,
@@ -24,6 +24,13 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- data/plates/PROVENANCE.md
+- data/plates/_decode/es-provinces.yml
+- data/plates/_meta/classes.yml
+- data/plates/de.yml
+- data/plates/es.yml
+- data/plates/nl.yml
+- data/plates/us-fl.yml
 - data/vehicles.json
 - exe/vehicles-mcp
 - lib/generators/vehicles/install_generator.rb
@@ -38,6 +45,9 @@ files:
 - lib/vehicles/mcp_server.rb
 - lib/vehicles/model.rb
 - lib/vehicles/other_option.rb
+- lib/vehicles/plates.rb
+- lib/vehicles/plates/jurisdiction.rb
+- lib/vehicles/plates/series.rb
 - lib/vehicles/providers/hosted_provider.rb
 - lib/vehicles/providers/local_provider.rb
 - lib/vehicles/railtie.rb