vehicles 0.1.0

data/lib/vehicles/providers/local_provider.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Vehicles
+  module Providers
+    # The always-available provider, backed by the bundled dataset. It answers
+    # whatever the local snapshot knows and returns nil for everything it doesn't
+    # (years/segment/image today) — which is exactly what makes graceful
+    # degradation work: the hosted provider enriches, this one guarantees the
+    # gem never breaks when the hosted data is absent.
+    module LocalProvider
+      module_function
+
+      def available?
+        true
+      end
+
+      # 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
+    end
+  end
+end

data/lib/vehicles/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Vehicles
+  # Wires the gem into Rails without forcing anything: it only registers the
+  # ActiveModel validators, and only once ActiveRecord/ActiveModel is loaded.
+  # There's no engine, no migration, no table — the data lives in the bundled
+  # JSON, so there's nothing to install.
+  class Railtie < ::Rails::Railtie
+    initializer "vehicles.validators" do
+      ActiveSupport.on_load(:active_record) { Vehicles.load_validators! }
+      # Also cover plain-ActiveModel hosts (e.g. a Tableless model) loaded early.
+      Vehicles.load_validators! if defined?(ActiveModel::EachValidator)
+    end
+  end
+end

data/lib/vehicles/refresher.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Vehicles
+  # Pulls the latest published dataset from the VehiclesDB data repo (config.data_url)
+  # into a local file cache (config.cache_path). This is how data fixes and new
+  # makes reach an app WITHOUT a gem upgrade — schedule `Vehicles.refresh!` (e.g.
+  # a daily job) and loads will prefer the cached data over the bundled snapshot.
+  #
+  # Error-isolated by design: a failed/partial download never corrupts the cache
+  # and never raises — the gem just keeps serving whatever it already had
+  # (cached, or the bundled snapshot). Atomic write so a reader never sees a
+  # half-written file.
+  module Refresher
+    MAX_REDIRECTS = 3
+
+    module_function
+
+    # Download + cache the latest dataset. Returns true on success, false on any
+    # failure (network, non-200, unparseable/empty payload). Never raises.
+    def refresh!
+      config = Vehicles.configuration
+      body = fetch(config.data_url, config.refresh_timeout)
+      return false unless valid_payload?(body)
+
+      write_atomic(config.cache_path, body)
+      Vehicles.reload! # drop the in-memory dataset so the next access uses fresh data
+      true
+    rescue StandardError => e
+      Vehicles.logger&.warn("[vehicles] refresh failed: #{e.class}: #{e.message}")
+      false
+    end
+
+    # True when a refreshed dataset is cached on disk.
+    def cached?
+      path = Vehicles.configuration.cache_path
+      !path.to_s.empty? && File.exist?(path)
+    end
+
+    def cached_path
+      cached? ? Vehicles.configuration.cache_path : nil
+    end
+
+    # Remove the cached dataset (the gem falls back to the bundled snapshot).
+    def clear_cache!
+      path = Vehicles.configuration.cache_path
+      File.delete(path) if path && File.exist?(path)
+      Vehicles.reload!
+    end
+
+    # --- internals -----------------------------------------------------------
+
+    # A payload is only accepted if it parses and looks like our dataset, so a
+    # CDN error page / truncated download can never replace good data.
+    def valid_payload?(body)
+      return false if body.to_s.empty?
+
+      data = JSON.parse(body)
+      data.is_a?(Hash) && data["makes"].is_a?(Array) && !data["makes"].empty?
+    rescue JSON::ParserError
+      false
+    end
+
+    def fetch(url, timeout, redirects_left = MAX_REDIRECTS)
+      require "net/http"
+      require "uri"
+
+      uri = URI(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+
+      response = http.get(uri.request_uri, "Accept" => "application/json")
+      case response
+      when Net::HTTPSuccess
+        response.body
+      when Net::HTTPRedirection
+        return nil if redirects_left <= 0
+
+        fetch(response["location"], timeout, redirects_left - 1)
+      end
+    end
+
+    def write_atomic(path, body)
+      require "fileutils"
+      FileUtils.mkdir_p(File.dirname(path))
+      tmp = "#{path}.#{Process.pid}.tmp"
+      File.write(tmp, body)
+      File.rename(tmp, path) # atomic on the same filesystem
+    end
+  end
+end

data/lib/vehicles/validators/vehicle_make_validator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Drop-in validator: `validates :make, vehicle_make: true`.
+#
+# Rails resolves the `vehicle_make:` key to this top-level constant automatically
+# (camelize + "Validator"), so no registration is needed — requiring the file is
+# enough. Forgiving (aliases/case/slug) like every other lookup, and defensive:
+# blank values pass (pair with `presence: true` if you want them rejected), and
+# any internal error degrades to a generic message instead of blowing up a form.
+class VehicleMakeValidator < ActiveModel::EachValidator
+  def validate_each(record, attribute, value)
+    return if value.blank?
+    return if Vehicles.make(value)
+
+    record.errors.add(attribute, options[:message] || "is not a recognized vehicle make")
+  rescue StandardError => e
+    Vehicles.logger&.error("[vehicles] vehicle_make validation error: #{e.message}")
+    record.errors.add(attribute, options[:message] || "is not a recognized vehicle make")
+  end
+end

data/lib/vehicles/validators/vehicle_model_validator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Drop-in validator: `validates :model, vehicle_model: { make: :make }`.
+#
+# Checks that the value is a real model OF the make held in another attribute.
+# Pass `make:` pointing at the attribute that holds the make (defaults to :make).
+#
+#   validates :model, vehicle_model: { make: :car_make }
+#
+# Defensive by design: blank model passes; an unknown/blank make can't disprove
+# the model, so it passes (let the make's own validator flag that); errors never
+# raise out of a form submission.
+class VehicleModelValidator < ActiveModel::EachValidator
+  def validate_each(record, attribute, value)
+    return if value.blank?
+
+    make_attribute = options[:make] || :make
+    make_value = record.respond_to?(make_attribute) ? record.public_send(make_attribute) : nil
+    make = Vehicles.make(make_value)
+    return if make.nil? # unknown make -> defer to the make validator
+    return if make.model(value)
+
+    record.errors.add(attribute, options[:message] || "is not a recognized #{make.name} model")
+  rescue StandardError => e
+    Vehicles.logger&.error("[vehicles] vehicle_model validation error: #{e.message}")
+    record.errors.add(attribute, options[:message] || "is not a recognized vehicle model")
+  end
+end

data/lib/vehicles/version.rb

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

data/lib/vehicles.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require_relative "vehicles/version"
+require_relative "vehicles/configuration"
+require_relative "vehicles/make"
+require_relative "vehicles/model"
+require_relative "vehicles/color"
+require_relative "vehicles/dataset"
+require_relative "vehicles/refresher"
+require_relative "vehicles/providers/local_provider"
+require_relative "vehicles/providers/hosted_provider"
+
+# Car makes & models for your Rails app — dropdowns, search, validation. Bundled
+# data, zero config, no network calls. Standalone first; an SDK for the hosted
+# VehiclesDB API second.
+#
+#   Vehicles.makes                   # => ["Alfa Romeo", "Audi", "BMW", ...]
+#   Vehicles.models("VW")            # => ["Golf", "Polo", "Tiguan", ...]
+#   Vehicles.find("vw golf")         # => #<Vehicles::Model "Volkswagen Golf">
+#   Vehicles.make_options            # => [["Alfa Romeo", "alfa-romeo"], ...]  (for select)
+module Vehicles
+  class Error < StandardError; end
+
+  # The bundled snapshot, packaged in the gem. Overridable via `Vehicles.data_path=`.
+  DATA_PATH = File.expand_path("../data/vehicles.json", __dir__)
+
+  class << self
+    # --- configuration -------------------------------------------------------
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    # Reset config + caches (config, data path, dataset, providers). Primarily
+    # for the test suite — genuinely returns the gem to a pristine state.
+    def reset_configuration!
+      @configuration = Configuration.new
+      @providers = nil
+      @data_path = nil
+      Dataset.reset!
+      Providers::HostedProvider.reset!
+    end
+
+    # --- data access ---------------------------------------------------------
+
+    # Path to the bundled snapshot (or an explicit override via `data_path=`).
+    def data_path
+      @data_path || DATA_PATH
+    end
+
+    attr_writer :data_path, :logger
+
+    # The dataset file actually in effect: an explicit override wins; otherwise a
+    # refreshed cache (if present and `use_cache`); otherwise the bundled snapshot.
+    # This is how a refresh reaches the running app — no gem upgrade needed.
+    def active_data_path
+      return @data_path if @data_path
+      return Refresher.cached_path if configuration.use_cache && Refresher.cached?
+
+      DATA_PATH
+    end
+
+    def dataset
+      Dataset.load(active_data_path)
+    end
+
+    # Pull the latest published dataset into the local cache, so data fixes / new
+    # makes land WITHOUT a gem upgrade. Returns true/false; never raises. Schedule
+    # it (e.g. a daily job — `rails g vehicles:install` sets one up).
+    def refresh!
+      Refresher.refresh!
+    end
+
+    # Drop the in-memory dataset so the next access reloads from disk (after a
+    # refresh, a cache clear, or a `data_path=` change).
+    def reload!
+      Dataset.reset!
+    end
+
+    # Version of the dataset currently in effect (refreshed cache or bundled),
+    # e.g. "2026.06.0".
+    def data_version
+      dataset.version
+    end
+
+    # Region the bundled data covers, as a Symbol, e.g. :eu.
+    def region
+      dataset.region.to_s.downcase.to_sym
+    end
+
+    # --- core query API ------------------------------------------------------
+
+    # Make display names. => ["Abarth", "Alfa Romeo", ...]
+    def makes(kind: nil, region: nil)
+      dataset.makes(kind: kind, region: region || configuration.region).map(&:name)
+    end
+
+    # Model display names for a make. => ["Golf", "Polo", ...]. Unknown make => [].
+    def models(make, kind: nil, body_type: nil, region: nil)
+      region ||= configuration.region
+      return [] if region && !dataset.region?(region)
+
+      found = make(make)
+      found ? found.models(kind: kind, body_type: body_type).map(&:name) : []
+    end
+
+    # The rich Make object (or nil). Forgiving: name, slug, or alias.
+    def make(query)
+      dataset.find_make(query)
+    end
+
+    # Resolve a free-text "make + model" string into one Model (or nil).
+    def find(query)
+      dataset.find_model(query)
+    end
+
+    # Resolve a stored make + model PAIR into a Model (or nil). The structured
+    # counterpart to `find` (which parses one free-text string) — reach for this
+    # when your records keep make and model in separate columns and you want the
+    # model's metadata (kind, body_type, …) back.
+    #   Vehicles.model("Audi", "A3")   # => #<Vehicles::Model "Audi A3">
+    #   Vehicles.model("vw", "golf")   # forgiving, like every other lookup
+    def model(make_name, model_name)
+      found = make(make_name)
+      found&.model(model_name)
+    end
+
+    # Every model matching a query, ranked. => [Vehicles::Model, ...]
+    def search(query)
+      dataset.search(query)
+    end
+
+    # --- colors (canonical reference palette) --------------------------------
+
+    # The canonical color palette, frequency-ordered. => [Vehicles::Color, ...]
+    def colors
+      Colors::ALL
+    end
+
+    # [[name, slug], ...] for a Rails `select`. Names are English — localize the
+    # labels in your app; the slug is the stable value you store.
+    def color_options
+      Colors::ALL.map { |c| [c.name, c.slug] }
+    end
+
+    # Resolve a color by slug or name (forgiving: case, diacritics, synonyms like
+    # "gray"→grey, "navy"→blue). Returns a Vehicles::Color, or nil.
+    def color(query)
+      q = normalize(query)
+      return nil if q.empty?
+
+      Colors::BY_SLUG[q] || Colors::BY_NAME[q] || Colors::BY_SLUG[Colors::SYNONYMS[q]]
+    end
+
+    # [[label, value], ...] of makes for a Rails `select`.
+    def make_options(kind: nil, region: nil)
+      dataset.makes(kind: kind, region: region || configuration.region).map { |m| [m.name, m.slug] }
+    end
+
+    # [[label, value], ...] of a make's models for a Rails `select`. Unknown => [].
+    def model_options(make, kind: nil, body_type: nil)
+      found = make(make)
+      found ? found.model_options(kind: kind, body_type: body_type) : []
+    end
+
+    # A { make => [model names] } map for the given filters — everything you need
+    # to build a dependent make → model picker entirely on the client: embed it
+    # once (`Vehicles.catalog(kind: :car).to_json`) and switch the model list in a
+    # few lines of JS. No endpoint, no extra request, instant. The whole car
+    # catalog is small (tens of KB), so this is the simplest path for most apps.
+    #   Vehicles.catalog(kind: :car)   # => { "Audi" => ["A3", "A4", ...], ... }
+    def catalog(kind: nil, region: nil)
+      makes(kind: kind, region: region).to_h do |name|
+        [name, models(name, kind: kind, region: region)]
+      end
+    end
+
+    # --- provider resolution (hosted enrichment, optional) -------------------
+
+    # Ask each available provider for an attribute, hosted first, until one gives
+    # a non-nil answer. Returns nil if none can. Never raises. Backs Model#years
+    # / #segment / #image.
+    def resolve(attribute, model, **opts)
+      providers.each do |provider|
+        next unless provider.available?
+
+        value = provider.public_send(attribute, model, **opts)
+        return value unless value.nil?
+      rescue StandardError => e
+        # A misbehaving provider must never break a model read — log and move on.
+        logger&.error("[vehicles] provider #{provider} failed on #{attribute}: #{e.message}")
+        next
+      end
+      nil
+    end
+
+    def providers
+      @providers ||= [Providers::HostedProvider, Providers::LocalProvider]
+    end
+
+    # --- helpers -------------------------------------------------------------
+
+    # Match-normalize a string: fold diacritics, downcase, collapse anything
+    # non-alphanumeric to single spaces. "Mercedes-Benz" => "mercedes benz",
+    # "Škoda" => "skoda". Used everywhere lookups need to be forgiving — so it must
+    # NEVER raise (the API contract is "garbage in => empty/nil out, not an error").
+    def normalize(str)
+      fold_diacritics(str).downcase.gsub(/[^a-z0-9]+/, " ").strip
+    end
+
+    # Slugify a display name: "Alfa Romeo" => "alfa-romeo", "Škoda" => "skoda".
+    def slugify(str)
+      fold_diacritics(str).downcase.gsub(/[^a-z0-9]+/, "-").gsub(/(\A-|-\z)/, "")
+    end
+
+    # Shared diacritic folding for normalize/slugify. NFKD splits "š" into "s" + a
+    # combining caron; we strip the combining marks (\p{Mn}) BEFORE the separator
+    # gsub, or "Škoda" would become "s koda". Defends against non-UTF-8/invalid
+    # encodings (e.g. a binary string) so callers never hit Encoding errors.
+    def fold_diacritics(str)
+      s = str.to_s
+      s = s.dup.force_encoding(Encoding::UTF_8) unless s.encoding == Encoding::UTF_8
+      s = s.scrub("") unless s.valid_encoding?
+      s.unicode_normalize(:nfkd).gsub(/\p{Mn}+/, "")
+    end
+
+    def logger
+      @logger ||= (defined?(Rails) && Rails.respond_to?(:logger) ? Rails.logger : nil)
+    end
+
+    # Require the ActiveModel validators (idempotent; no-op without ActiveModel).
+    def load_validators!
+      return if @validators_loaded
+      return unless defined?(ActiveModel::EachValidator)
+
+      require_relative "vehicles/validators/vehicle_make_validator"
+      require_relative "vehicles/validators/vehicle_model_validator"
+      @validators_loaded = true
+    end
+  end
+end
+
+# Loaded after the module so its lookup tables can use Vehicles.normalize.
+require_relative "vehicles/colors"
+
+# Rails integration is opt-in and detected at load time — the gem works fine in
+# plain Ruby without it.
+require_relative "vehicles/railtie" if defined?(Rails::Railtie)
+# If ActiveModel is already present (e.g. required directly), wire validators now.
+Vehicles.load_validators! if defined?(ActiveModel::EachValidator)

data/sig/vehicles.rbs

@@ -0,0 +1,94 @@
+# Type signatures for the public API. (Best-effort; the README and code are the
+# source of truth.)
+
+module Vehicles
+  VERSION: String
+  DATA_PATH: String
+
+  def self.configuration: () -> Configuration
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.reset_configuration!: () -> void
+
+  def self.data_path: () -> String
+  def self.data_version: () -> String?
+  def self.region: () -> Symbol
+
+  def self.makes: (?kind: Symbol?, ?region: Symbol?) -> Array[String]
+  def self.models: (untyped make, ?kind: Symbol?, ?body_type: Symbol?, ?region: Symbol?) -> Array[String]
+  def self.make: (untyped query) -> Make?
+  def self.find: (untyped query) -> Model?
+  def self.model: (untyped make_name, untyped model_name) -> Model?
+  def self.search: (untyped query) -> Array[Model]
+  def self.make_options: (?kind: Symbol?, ?region: Symbol?) -> Array[[String, String]]
+  def self.model_options: (untyped make, ?kind: Symbol?, ?body_type: Symbol?) -> Array[[String, String]]
+  def self.catalog: (?kind: Symbol?, ?region: Symbol?) -> Hash[String, Array[String]]
+
+  def self.colors: () -> Array[Color]
+  def self.color: (untyped query) -> Color?
+  def self.color_options: () -> Array[[String, String]]
+
+  def self.dataset: () -> Dataset
+  def self.data_path: () -> String
+  def self.data_path=: (String) -> void
+  def self.active_data_path: () -> String
+  def self.refresh!: () -> bool
+  def self.reload!: () -> void
+  def self.normalize: (untyped str) -> String
+  def self.slugify: (untyped str) -> String
+
+  class Error < StandardError
+  end
+
+  class Configuration
+    attr_accessor region: Symbol
+    attr_accessor api_key: String?
+    attr_accessor api_base_url: String
+    attr_accessor api_timeout: Integer
+    attr_reader aliases: Hash[String, String]
+    attr_accessor data_url: String
+    attr_accessor cache_path: String
+    attr_accessor use_cache: bool
+    attr_accessor refresh_timeout: Integer
+  end
+
+  class Make
+    attr_reader name: String
+    attr_reader slug: String
+    attr_reader aliases: Array[String]
+    attr_reader kinds: Array[Symbol]
+    def models: (?kind: Symbol?, ?body_type: Symbol?) -> Array[Model]
+    def model: (untyped query) -> Model?
+    def model_names: (?kind: Symbol?, ?body_type: Symbol?) -> Array[String]
+    def model_options: (?kind: Symbol?, ?body_type: Symbol?) -> Array[[String, String]]
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class Color
+    attr_reader slug: String
+    attr_reader name: String
+    attr_reader hex: String
+    def to_h: () -> Hash[Symbol, String]
+  end
+
+  class Model
+    KINDS: Array[Symbol]
+    BODY_TYPES: Array[Symbol]
+    attr_reader make: String
+    attr_reader make_slug: String
+    attr_reader name: String
+    attr_reader kind: Symbol
+    attr_reader body_type: Symbol
+    def full_name: () -> String
+    def to_s: () -> String
+    def slug: () -> String
+    def model_slug: () -> String
+    def to_h: () -> Hash[Symbol, untyped]
+    # predicate sugar for each kind/body type: car?, suv?, hatchback?, coupe?, ...
+    def car?: () -> bool
+    def suv?: () -> bool
+    def hatchback?: () -> bool
+    def years: () -> Range[Integer]?
+    def segment: () -> Symbol?
+    def image: (?year: Integer?, ?color: untyped) -> String?
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: vehicles
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- rameerez
+bindir: bin
+cert_chain: []
+date: 2026-06-23 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,
+  search, and validation. No API keys, no network calls, no database table — the data
+  lives inside the gem and just works. It also acts as the SDK for the hosted VehiclesDB
+  API. Code is MIT; the bundled data is CC-BY 4.0 (derived from RDW Open Data).
+email:
+- rubygems@rameerez.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- data/vehicles.json
+- lib/generators/vehicles/install_generator.rb
+- lib/generators/vehicles/templates/initializer.rb
+- lib/generators/vehicles/templates/vehicles_refresh_job.rb
+- lib/vehicles.rb
+- lib/vehicles/color.rb
+- lib/vehicles/colors.rb
+- lib/vehicles/configuration.rb
+- lib/vehicles/dataset.rb
+- lib/vehicles/make.rb
+- lib/vehicles/model.rb
+- lib/vehicles/providers/hosted_provider.rb
+- lib/vehicles/providers/local_provider.rb
+- lib/vehicles/railtie.rb
+- lib/vehicles/refresher.rb
+- lib/vehicles/validators/vehicle_make_validator.rb
+- lib/vehicles/validators/vehicle_model_validator.rb
+- lib/vehicles/version.rb
+- sig/vehicles.rbs
+homepage: https://github.com/rameerez/vehicles
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/rameerez/vehicles
+  source_code_uri: https://github.com/rameerez/vehicles/tree/main
+  changelog_uri: https://github.com/rameerez/vehicles/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Car makes & models for your Rails app — dropdowns, search, validation. Zero
+  config, no API keys.
+test_files: []