usa 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: baafe271decb488334f07d38d4312f97c37a031cbfe8d142fc91d0c6b9de0f9a
-  data.tar.gz: 17800009d94fccacc4f14845549909084552018624996963fed80d72630a79d6
+  metadata.gz: 03b2542ffafa029a4598cdcd0226b8c088fb86b581048ac9a0ad31143bf24e77
+  data.tar.gz: df5d33713273555f55bfef5f55b7c179095737de5aafb65a3ebaec7928ad78f1
 SHA512:
-  metadata.gz: 91179ce7f344c77569bcee54f8b15a4c0afd2781f7658a8d225ea353a4b44d43ddca5c9d1efbbdcfacf1eb8ec062c455730364bc99893571b9962961ea7a4284
-  data.tar.gz: bdac914175b069d651ea61be39d48896cee8401506a415f7a399d7607226f9a7175f30fd7b8f3c09d243253dcfae958be3b41941b52cc9ffafc87c9e6327a17e
+  metadata.gz: cdcae36d574ba780eb0443dac939f3e3c01768a8bcb64e658eb0c8b4562cb6b2f6c53c2c16d8f59474fcc83b1eb9f0bfae192271a57027b2613c1ff97098f0bd
+  data.tar.gz: ca491f71bf66c03ca86ebe972122fd0b2afbf9fb8568cb64f0f3fd05089e334e91ba80ad65e62bae9d3ae2cc919189235a5c5ba40e64b0ab48ea42d267aeb88e

data/CHANGELOG.md

@@ -7,6 +7,26 @@ For more information about changelogs, check [Keep a Changelog](http://keepachan
 
 ## [Unreleased]
 
+## 0.4.0 - 2026-09-15
+
+* [Breaking change] The models are `State`, `County`, `City`, `CityCounty` and `ZIP`, at the
+  top level rather than under `USA::`. A host writes `belongs_to :zip` and Active Record finds
+  the class, where before it refused anything but `class_name: 'USA::ZIP'` -- its `compute_type`
+  wants a class whose own name is the one it asked for, so no alias or configuration could stand
+  in. The `model_name` overrides that made the old classes answer as `ZIP` and `County` are gone
+  with the namespace they were papering over
+* [Breaking change] The tables are `states`, `counties`, `cities`, `city_counties` and `zips`.
+  A host that wants them to itself sets `USA.table_name_prefix = 'usa_'` in an initializer and
+  gets the old names back -- one setting, read wherever a table is named, migrations included
+* [Feature] `USA.verify_models` refuses a host whose own class stands where one of these models
+  should be, at boot and in one sentence. Zeitwerk gives an app's file precedence over an
+  engine's, silently, so a host holding `app/models/city.rb` would otherwise find every
+  association here pointing at a class this gem knows nothing about
+* [Feature] `USA.seed` passes over a table the host never created, so an app that joins to three
+  of the five installs three and seeds three. `bin/rails db:usa:seed` goes on working there
+* [Feature] `USA.table` names a table the way the host does, which is what the shipped migrations
+  now create and what a host's own migration can read
+
 ## 0.3.0 - 2026-09-14
 
 * [Feature] Every model answers by the word a host means rather than by the table under it:

data/README.md

@@ -12,7 +12,7 @@ To install on your system, run
 
 To use inside a bundled Ruby project, add this line to the `Gemfile`:
 
-    gem 'usa', '~> 0.3.0'
+    gem 'usa', '~> 0.4.0'
 
 Below 1.0 the pin stops at the next minor rather than the next major, because that is where a
 breaking change may still land. It becomes `~> 1.0` once the API is settled on purpose.
@@ -27,45 +27,85 @@ bin/rails db:migrate      # the five tables, and every row in them
 The last one takes about a minute: it writes 51 states, 3,144 counties, some 32,000 cities and
 some 41,000 ZIPs.
 
+Install only the tables you join to. Delete the migrations for the rest before you run them, and
+`USA.seed` passes over what is not there — an app that never asks what city an address is in
+keeps three tables rather than five.
+
 **A database made from `db/schema.rb` has the tables and none of the rows.** A dump carries no
-data, so `db:schema:load`, `db:test:prepare` and a fresh clone all leave the five tables empty.
-Run `bin/rails db:usa:seed`, or call `USA.seed` from your own `db/seeds.rb`. The same command is
-how a database catches up with a release that added rows: every write is an upsert keyed on the
-code or the FIPS, so it inserts what is missing, updates what this gem owns, and leaves the id
-of every row you already had exactly where it was.
+data, so `db:schema:load`, `db:test:prepare` and a fresh clone all leave the tables empty. Run
+`bin/rails db:usa:seed`, or call `USA.seed` from your own `db/seeds.rb`. The same command is how
+a database catches up with a release that added rows: every write is an upsert keyed on the code
+or the FIPS, so it inserts what is missing, updates what this gem owns, and leaves the id of
+every row you already had exactly where it was.
 
 ## What you get
 
 ```ruby
-zip = USA::ZIP.find_by code: '90210'  # => #<USA::ZIP>
-zip.city                              # => 'Beverly Hills'
-zip.time_zone                         # => 'Pacific Time (US & Canada)'
-zip.county                            # => #<USA::County>
-zip.county.fips                       # => '06037'
-zip.county.state.code                 # => 'CA'
+zip = ZIP.find_by code: '90210'  # => #<ZIP>
+zip.city                         # => 'Beverly Hills'
+zip.time_zone                    # => 'Pacific Time (US & Canada)'
+zip.county                       # => #<County>
+zip.county.fips                  # => '06037'
+zip.county.state.code            # => 'CA'
 
 county = zip.county
-county.zips_count                     # => 508
-county.cities                         # => [#<USA::City>, ...]
+county.zips_count                # => 508
+county.cities                    # => [#<City>, ...]
 
 state = county.state
-state.counties_count                  # => 58
-state.counties                        # => [#<USA::County>, ...]
-state.cities                          # => [#<USA::City>, ...]
+state.counties_count             # => 58
+state.counties                   # => [#<County>, ...]
+state.cities                     # => [#<City>, ...]
 ```
 
 A state has a `code`, a `fips` and a `name`. A county has a `fips`, a `name` and a state. A city
 has a `fips` -- a Census place code, unique within its state rather than nationally -- a `name`,
 a state, and the one or more counties it lies in, since a city may cross a county line. A ZIP has
 a `code`, the `city` it is addressed as, a `time_zone` named as Rails names one, and one county.
+
+That county and that city are the main one rather than the only one. A ZIP is a delivery route
+rather than an area, and many of them cross a county line: this gem names the county the route
+is chiefly in and the city it is chiefly addressed to, and holds nothing about the others. A
+city is the exception, keeping every county it lies in, which is why `city.counties` answers
+more than one.
+
 Every one of the four also has a `google_place_id`, the ID Google gives the place, which is what
 draws a table of them as a map. It is filled for every state, county and ZIP that Google keeps
 as an area of its kind, and blank for the few it keeps only as a city -- the District of
 Columbia, Broomfield County, Wrangell -- for the ZIPs it folds into a neighbor's, and for every
 city until a release fills them.
 
-Two counter caches are kept by the seed rather than by a callback: `usa_states.counties_count`
-and `usa_counties.zips_count`.
+Two counter caches are kept by the seed rather than by a callback: `states.counties_count` and
+`counties.zips_count`.
+
+## The names are yours to write, not to choose
+
+`State`, `County`, `City`, `CityCounty` and `ZIP` are this gem's classes, on `states`,
+`counties`, `cities`, `city_counties` and `zips`. They are the words your routes, forms,
+partials and locale keys already use, so `belongs_to :zip` finds the class, `zips_path` draws
+the page and `zip[...]` names the field -- nothing has to be told which gem the model came from.
+
+Which means this gem takes five names in your app, and a class of your own called `Zip`, `City`
+or `State` cannot stand beside them. Rails gives your `app/models/city.rb` precedence over an
+engine's, silently, so the gem checks at boot and refuses to start rather than let every
+association here point at a class it knows nothing about:
+
+    The usa gem defines City, and a class of your own has taken the name. Rename yours: …
+
+The gem also registers `USA`, `ZIP` and `FIPS` as acronyms, so `ZIP` is the spelling everywhere
+-- a heading, a route helper, a migration's class name.
+
+If you want these tables to themselves, name them:
+
+```ruby
+# config/initializers/usa.rb
+USA.table_name_prefix = 'usa_'
+```
+
+One setting, read wherever a table is named: the models, the counter queries, and the migrations
+the generator hands you. Set it before anything queries, which an initializer is. The class
+names are not configurable -- Active Record resolves `belongs_to :zip` by asking for a class
+called `ZIP`, and nothing but a class of that name will do.
 
 ## Making them yours
 
@@ -80,31 +120,32 @@ ActiveSupport.on_load(:usa_zip) do
 end
 ```
 
-`:usa_state`, `:usa_county`, `:usa_city` and `:usa_zip` are the four, and `:usa_record` is where
-an app says how all of them connect -- a reading role, say, which these models otherwise know
-nothing about:
+`:usa_state`, `:usa_county`, `:usa_city`, `:usa_city_county` and `:usa_zip` are the five, and
+`:usa_record` is where an app says how all of them connect -- a reading role, say, which these
+models otherwise know nothing about:
 
 ```ruby
 ActiveSupport.on_load(:usa_record) { connects_to database: { writing: :primary, reading: :reader } }
 ```
 
-Each model answers by the word you mean rather than by the table under it, so a page listing
-ZIPs writes `zips_path`, a form posts `zip[...]`, a partial lives at `zips/_row` and a locale
-key reads `zip` -- while the table stays `usa_zips`. A gem that resolves a model from a route
-finds it without being told.
-
 Columns of your own go on these tables in a migration of your own. They survive every seed: this
 gem writes only the columns it ships.
 
 ## Adopting it in an app that already has these tables
 
-The gem registers `USA`, `ZIP` and `FIPS` as acronyms, so a class of yours called `Zip` stops
-being found the day you install it -- rename it, or reach `USA::ZIP` instead. Point your foreign
-keys at `usa_zips.id` rather than at a `zips` of your own, and where your rows were loaded with
-explicit ids, run `setval` on the sequence before the first seed, or the first insert collides.
+Your tables are already called `states`, `counties` and `zips`, so there is nothing to rename:
+add the columns this gem's own carry that yours lack -- `google_place_id`, the counter caches,
+a ZIP's city and time zone -- and seed. Every id stays where it is, because the seed upserts on
+the code or the FIPS rather than on the id, and every foreign key of yours goes on pointing at
+the row it pointed at.
+
+Delete the models you had for them, and say through the load hooks what they said. Where your
+rows were loaded with explicit ids, run `setval` on the sequence before the first seed, or the
+first insert collides.
 
-The gem does not support an app that sets `ActiveRecord::Base.table_name_prefix`: its migrations
-name `usa_states` while the models would look for the prefix and yours together.
+Two things to know. A class of yours called `Zip` stops being found the day you install this,
+which the boot check will tell you. And `State` and `County` cascade to `cities` with
+`dependent: :destroy`, so an app that skipped those tables must not destroy one.
 
 ## Development
 

data/app/models/{usa/city.rb → city.rb}

@@ -1,5 +1,5 @@
 # A city, town or census designated place: what a street address is addressed to.
-class USA::City < USA::Record
+class City < USA::Record
   include USA::Seeded
 
   belongs_to :state
@@ -14,16 +14,13 @@ class USA::City < USA::Record
   # @return [String] the default representation (used in views).
   def to_s = "#{name} (#{state.code})"
 
-  # The name Rails reads off this model: its route, its param key, its partial, its key.
-  def self.model_name = ActiveModel::Name.new(self, nil, 'City')
-
   class << self
   private
 
     def natural_key = %i[state_id fips]
 
     def seeds
-      states = USA::State.pluck(:code, :id).to_h
+      states = State.pluck(:code, :id).to_h
       csv('cities').lazy.map do |row|
         { fips: row['fips'], name: row['name'], state_id: states.fetch(row['state']),
           google_place_id: row['google_place_id'], }
@@ -32,4 +29,4 @@ class USA::City < USA::Record
   end
 end
 
-ActiveSupport.run_load_hooks :usa_city, USA::City
+ActiveSupport.run_load_hooks :usa_city, City

data/app/models/{usa/city_county.rb → city_county.rb}

@@ -1,5 +1,5 @@
 # Where a city lies: one row per county it reaches into, since a city may span several.
-class USA::CityCounty < USA::Record
+class CityCounty < USA::Record
   include USA::Seeded
 
   belongs_to :city
@@ -11,9 +11,10 @@ class USA::CityCounty < USA::Record
     def natural_key = %i[city_id county_id]
 
     def seeds
-      cities = USA::City.joins(:state).pluck('usa_states.code', :fips, 'usa_cities.id').
+      cities = City.joins(:state).
+        pluck("#{State.table_name}.code", :fips, "#{City.table_name}.id").
         to_h { |code, fips, id| [ [ code, fips ], id ] }
-      counties = USA::County.pluck(:fips, :id).to_h
+      counties = County.pluck(:fips, :id).to_h
       csv('cities').lazy.flat_map do |row|
         city_id = cities.fetch [ row['state'], row['fips'] ]
         row['counties'].split.map { |fips| { city_id:, county_id: counties.fetch(fips) } }
@@ -21,3 +22,5 @@ class USA::CityCounty < USA::Record
     end
   end
 end
+
+ActiveSupport.run_load_hooks :usa_city_county, CityCounty

data/app/models/{usa/county.rb → county.rb}

@@ -1,5 +1,5 @@
 # A county, parish, borough or census area: the division every ZIP is counted under.
-class USA::County < USA::Record
+class County < USA::Record
   include USA::Seeded
 
   belongs_to :state, counter_cache: true
@@ -11,29 +11,30 @@ class USA::County < USA::Record
   validates :fips, presence: true, length: { is: 5 }, uniqueness: true
   validates :name, presence: true
 
-  # How many ZIPs a county holds, asked of the rows: an upsert runs no callback to keep it.
-  ZIPS = 'SELECT COUNT(*) FROM usa_zips WHERE usa_zips.county_id = usa_counties.id'
-
   # Counts the ZIPs of every county the count is wrong for, and touches none of the others.
   # @return [void]
   def self.recount_zips
-    where("zips_count <> (#{ZIPS})").
-      update_all [ "zips_count = (#{ZIPS}), updated_at = ?", Time.current ]
+    where("zips_count <> (#{counted_zips})").
+      update_all [ "zips_count = (#{counted_zips}), updated_at = ?", Time.current ]
   end
 
   # @return [String] the default representation (used in views).
   def to_s = "#{name} (#{state.code})"
 
-  # The name Rails reads off this model: its route, its param key, its partial, its key.
-  def self.model_name = ActiveModel::Name.new(self, nil, 'County')
-
   class << self
   private
 
+    # How many ZIPs a county holds, asked of the rows: an upsert runs no callback to keep it.
+    def counted_zips
+      theirs = ZIP.table_name
+
+      "SELECT COUNT(*) FROM #{theirs} WHERE #{theirs}.county_id = #{table_name}.id"
+    end
+
     def natural_key = :fips
 
     def seeds
-      states = USA::State.pluck(:code, :id).to_h
+      states = State.pluck(:code, :id).to_h
       csv('counties').lazy.map do |row|
         { fips: row['fips'], name: row['name'], state_id: states.fetch(row['state']),
           google_place_id: row['google_place_id'], }
@@ -42,4 +43,4 @@ class USA::County < USA::Record
   end
 end
 
-ActiveSupport.run_load_hooks :usa_county, USA::County
+ActiveSupport.run_load_hooks :usa_county, County

data/app/models/{usa/state.rb → state.rb}

@@ -1,5 +1,5 @@
 # A state of the United States, or the District of Columbia.
-class USA::State < USA::Record
+class State < USA::Record
   include USA::Seeded
 
   has_many :counties, dependent: :destroy
@@ -9,25 +9,26 @@ class USA::State < USA::Record
   validates :fips, presence: true, length: { is: 2 }, uniqueness: true
   validates :name, presence: true, uniqueness: true
 
-  # How many counties a state holds, asked of the rows: an upsert runs no callback to keep it.
-  COUNTIES = 'SELECT COUNT(*) FROM usa_counties WHERE usa_counties.state_id = usa_states.id'
-
   # Counts the counties of every state the count is wrong for, and touches none of the others.
   # @return [void]
   def self.recount_counties
-    where("counties_count <> (#{COUNTIES})").
-      update_all [ "counties_count = (#{COUNTIES}), updated_at = ?", Time.current ]
+    where("counties_count <> (#{counted_counties})").
+      update_all [ "counties_count = (#{counted_counties}), updated_at = ?", Time.current ]
   end
 
   # @return [String] the default representation (used in views).
   def to_s = name
 
-  # The name Rails reads off this model: its route, its param key, its partial, its key.
-  def self.model_name = ActiveModel::Name.new(self, nil, 'State')
-
   class << self
   private
 
+    # How many counties a state holds, asked of the rows: an upsert runs no callback to keep it.
+    def counted_counties
+      theirs = County.table_name
+
+      "SELECT COUNT(*) FROM #{theirs} WHERE #{theirs}.state_id = #{table_name}.id"
+    end
+
     def natural_key = :code
 
     def seeds
@@ -39,4 +40,4 @@ class USA::State < USA::Record
   end
 end
 
-ActiveSupport.run_load_hooks :usa_state, USA::State
+ActiveSupport.run_load_hooks :usa_state, State

data/app/models/usa/record.rb

@@ -1,6 +1,10 @@
 # What every record this gem holds descends from, so a host says in one line how they connect.
 class USA::Record < ActiveRecord::Base
   self.abstract_class = true
+
+  # Read rather than stored, so an initializer setting it is in time whenever a model loads.
+  # @return [String] what this gem's tables are named with.
+  def self.table_name_prefix = USA.table_name_prefix
 end
 
 ActiveSupport.run_load_hooks :usa_record, USA::Record

data/app/models/{usa/zip.rb → zip.rb}

@@ -1,5 +1,5 @@
 # A ZIP code, and the city, time zone and county the Postal Service delivers it in.
-class USA::ZIP < USA::Record
+class ZIP < USA::Record
   include USA::Seeded
 
   belongs_to :county, counter_cache: true
@@ -11,16 +11,13 @@ class USA::ZIP < USA::Record
   # @return [String] the default representation (used in views).
   def to_s = code
 
-  # The name Rails reads off this model: its route, its param key, its partial, its key.
-  def self.model_name = ActiveModel::Name.new(self, nil, 'ZIP')
-
   class << self
   private
 
     def natural_key = :code
 
     def seeds
-      counties = USA::County.pluck(:fips, :id).to_h
+      counties = County.pluck(:fips, :id).to_h
       csv('zips').lazy.map do |row|
         { code: row['code'], city: row['city'], time_zone: row['time_zone'],
           county_id: counties.fetch(row['county']), google_place_id: row['google_place_id'], }
@@ -29,4 +26,4 @@ class USA::ZIP < USA::Record
   end
 end
 
-ActiveSupport.run_load_hooks :usa_zip, USA::ZIP
+ActiveSupport.run_load_hooks :usa_zip, ZIP

data/db/migrate/{20260914120000_create_usa_states.rb → 20260914120000_create_states.rb}

@@ -1,6 +1,6 @@
-class CreateUSAStates < ActiveRecord::Migration[8.1]
+class CreateStates < ActiveRecord::Migration[8.1]
   def change
-    create_table :usa_states do |t|
+    create_table USA.table(:states) do |t|
       t.string :code, limit: 2, null: false, index: { unique: true }
       t.string :fips, limit: 2, null: false, index: { unique: true }
       t.string :name, null: false, index: { unique: true }

data/db/migrate/{20260914120001_create_usa_counties.rb → 20260914120001_create_counties.rb}

@@ -1,9 +1,9 @@
-class CreateUSACounties < ActiveRecord::Migration[8.1]
+class CreateCounties < ActiveRecord::Migration[8.1]
   def change
-    create_table :usa_counties do |t|
+    create_table USA.table(:counties) do |t|
       t.string :fips, limit: 5, null: false, index: { unique: true }
       t.string :name, null: false, index: true
-      t.references :state, null: false, foreign_key: { to_table: :usa_states }
+      t.references :state, null: false, foreign_key: { to_table: USA.table(:states) }
       t.integer :zips_count, default: 0, null: false
       t.string :google_place_id
       t.timestamps

data/db/migrate/{20260914120002_create_usa_zips.rb → 20260914120002_create_zips.rb}

@@ -1,10 +1,10 @@
-class CreateUSAZips < ActiveRecord::Migration[8.1]
+class CreateZips < ActiveRecord::Migration[8.1]
   def change
-    create_table :usa_zips do |t|
+    create_table USA.table(:zips) do |t|
       t.string :code, limit: 5, null: false, index: { unique: true }
       t.string :city, null: false, index: true
       t.string :time_zone, null: false
-      t.references :county, null: false, foreign_key: { to_table: :usa_counties }
+      t.references :county, null: false, foreign_key: { to_table: USA.table(:counties) }
       t.string :google_place_id
       t.timestamps
     end

data/db/migrate/{20260914120003_create_usa_cities.rb → 20260914120003_create_cities.rb}

@@ -1,9 +1,10 @@
-class CreateUSACities < ActiveRecord::Migration[8.1]
+class CreateCities < ActiveRecord::Migration[8.1]
   def change
-    create_table :usa_cities do |t|
+    create_table USA.table(:cities) do |t|
       t.string :fips, limit: 5, null: false
       t.string :name, null: false, index: true
-      t.references :state, null: false, index: false, foreign_key: { to_table: :usa_states }
+      t.references :state, null: false, index: false,
+        foreign_key: { to_table: USA.table(:states) }
       t.string :google_place_id
       t.timestamps
       t.index %i[state_id fips], unique: true

data/db/migrate/20260914120004_create_city_counties.rb

@@ -0,0 +1,10 @@
+class CreateCityCounties < ActiveRecord::Migration[8.1]
+  def change
+    create_table USA.table(:city_counties), id: false do |t|
+      t.references :city, null: false, index: false,
+        foreign_key: { to_table: USA.table(:cities) }
+      t.references :county, null: false, foreign_key: { to_table: USA.table(:counties) }
+      t.index %i[city_id county_id], unique: true
+    end
+  end
+end

data/lib/usa/engine.rb

@@ -2,8 +2,8 @@ require 'action_dispatch'
 require 'rails/engine'
 
 module USA
-  # Teaches Rails where this gem's models live, and prefixes their tables with `usa_`.
+  # Teaches Rails where this gem's models live, and refuses a host that has taken their names.
   class Engine < ::Rails::Engine
-    isolate_namespace USA
+    config.to_prepare { USA.verify_models ::State, ::County, ::City, ::CityCounty, ::ZIP }
   end
 end

data/lib/usa/version.rb

@@ -1,4 +1,4 @@
 module USA
   # The version of this gem, as RubyGems knows it.
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

data/lib/usa.rb

@@ -1,7 +1,7 @@
 require 'active_support/inflector'
 require 'csv'
 
-# Before the engine, so Zeitwerk reads usa/zip.rb as USA::ZIP and a heading says ZIP, not Zip.
+# Before the engine, so Zeitwerk reads zip.rb as ZIP and a heading says ZIP, not Zip.
 ActiveSupport::Inflector.inflections do |inflect|
   inflect.acronym 'USA'
   inflect.acronym 'ZIP'
@@ -13,11 +13,39 @@ require 'usa/engine'
 
 # The geography of the United States: the states, counties, cities and ZIPs an address names.
 module USA
+  # What every table this gem ships is named with. Empty, so a host joins to `states` and
+  # `zips`; set it to `usa_` from an initializer to keep this gem's tables to themselves.
+  mattr_accessor :table_name_prefix, default: ''
+
+  # Raised for every failure this gem reports, so a host can rescue one type.
+  class Error < StandardError; end
+
+  # The name one of this gem's tables goes by in the host, which is what its migrations create.
+  # @return [Symbol] prefixed table name.
+  def self.table(name) = :"#{table_name_prefix}#{name}"
+
   # Writes every row this release holds, keeping the id of every row the database already has.
+  # A table the host never created is passed over, so an app that joins to three of the five
+  # installs three and seeds them.
   # @return [void]
   def self.seed
-    [ USA::State, USA::County, USA::City, USA::CityCounty, USA::ZIP ].each(&:seed)
-    USA::State.recount_counties
-    USA::County.recount_zips
+    [ State, County, City, CityCounty, ZIP ].select(&:table_exists?).each(&:seed)
+    State.recount_counties
+    County.recount_zips
+  end
+
+  # Refuses a host's own class standing where one of this gem's models should be. Zeitwerk
+  # gives an app's file precedence over an engine's, silently, so without this a host holding
+  # `app/models/city.rb` would find every association of this gem's pointing at a class of its
+  # own.
+  # @param [Array<Class>] models the classes the names this gem takes answer to.
+  # @return [void]
+  def self.verify_models(*models)
+    theirs = models.reject { |model| model < Record }
+    return if theirs.empty?
+
+    raise Error, "The usa gem defines #{theirs.to_sentence}, and a class of your own has " \
+      'taken the name. Rename yours: Rails gives an app’s file precedence over an engine’s, ' \
+      'silently, so the models this gem ships would point at a class it knows nothing about.'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: usa
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -47,18 +47,18 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- app/models/city.rb
+- app/models/city_county.rb
 - app/models/concerns/usa/seeded.rb
-- app/models/usa/city.rb
-- app/models/usa/city_county.rb
-- app/models/usa/county.rb
+- app/models/county.rb
+- app/models/state.rb
 - app/models/usa/record.rb
-- app/models/usa/state.rb
-- app/models/usa/zip.rb
-- db/migrate/20260914120000_create_usa_states.rb
-- db/migrate/20260914120001_create_usa_counties.rb
-- db/migrate/20260914120002_create_usa_zips.rb
-- db/migrate/20260914120003_create_usa_cities.rb
-- db/migrate/20260914120004_create_usa_city_counties.rb
+- app/models/zip.rb
+- db/migrate/20260914120000_create_states.rb
+- db/migrate/20260914120001_create_counties.rb
+- db/migrate/20260914120002_create_zips.rb
+- db/migrate/20260914120003_create_cities.rb
+- db/migrate/20260914120004_create_city_counties.rb
 - db/migrate/20260914120005_seed_usa.rb
 - db/seeds/cities.csv
 - db/seeds/counties.csv

data/db/migrate/20260914120004_create_usa_city_counties.rb

@@ -1,9 +0,0 @@
-class CreateUSACityCounties < ActiveRecord::Migration[8.1]
-  def change
-    create_table :usa_city_counties, id: false do |t|
-      t.references :city, null: false, index: false, foreign_key: { to_table: :usa_cities }
-      t.references :county, null: false, foreign_key: { to_table: :usa_counties }
-      t.index %i[city_id county_id], unique: true
-    end
-  end
-end