free_zipcode_data 1.0.6 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c86afee1e7972351d5d9f827348d4a0cd5cd3607e5ee5b2b7b4bc73db723bd2c
-  data.tar.gz: be4ee76892a7ebd900f9182360fd0b6263e9e523d35c50bafba4cf962ed74e8c
+  metadata.gz: 5a29b38bacdbf91fb1aad6732c0378eac3588a8bc9efd05c09b48470427da87e
+  data.tar.gz: 3b309917f7e87235ddc201f0db852d81b6f1310b85a32c18bc027600eceb34a3
 SHA512:
-  metadata.gz: 067d3c28ae188431f5d6418fa195fe72cbba273b266be6cae5aade8156e52d6c99cbe5767b31c3e6ce4214dd70a5969e93b85ea3f66a5eb3fa1434c1af7a2ffc
-  data.tar.gz: 2e80bb40c1e6b9863548a2f87630ce9e6ca0201d1520703b1b6f63d1b3020eaef8f6ce570df1d73365be3e4d7b7cd79cd5901a4677bf02956b20bbb2ce56e1c0
+  metadata.gz: 7d8e5b4a3b22359d46f3def15e4801d6ba39d70a8ec019bb1e302c6f98510b5fe6d0166bb7f9c2d8e35a3fda66572b4f4dbd6bc78a87874819864ea6225f8727
+  data.tar.gz: e26f46c2be8dfbb7f69c85a494de27a9607276e6958c56e58b4e63d20a2c9baca9da9fe95a35d4b3cb083f00f24bf0064e1be8aa815b1c6e417ed3cf32b48edd

data/.dockerignore

@@ -0,0 +1,10 @@
+.git
+vendor/bundle
+pkg
+stubs
+spec
+data
+build
+.claude
+docs
+*.sqlite3

data/.gitignore

@@ -5,3 +5,5 @@
 /stubs
 /vendor/bundle/
 /pkg
+.claude/
+docs/plans

data/.rubocop.yml

@@ -1,23 +1,24 @@
 AllCops:
-  TargetRubyVersion: 2.7
+  TargetRubyVersion: 3.4
 
   # Include gemspec and Rakefile
   Include:
-    - '**/*.gemspec'
-    - '**/*.podspec'
-    - '**/*.jbuilder'
-    - '**/*.rake'
-    - '**/Gemfile'
-    - '**/Rakefile'
-    - '**/Capfile'
-    - '**/Guardfile'
-    - '**/Podfile'
-    - '**/Thorfile'
-    - '**/Vagrantfile'
+    - "**/*.rb"
+    - "**/*.gemspec"
+    - "**/*.podspec"
+    - "**/*.jbuilder"
+    - "**/*.rake"
+    - "**/Gemfile"
+    - "**/Rakefile"
+    - "**/Capfile"
+    - "**/Guardfile"
+    - "**/Podfile"
+    - "**/Thorfile"
+    - "**/Vagrantfile"
   Exclude:
-    - 'vendor/**/*'
-    - 'stubs/**/*'
-    - 'spec/support/shared_contexts/*'
+    - "vendor/**/*"
+    - "stubs/**/*"
+    - "spec/support/shared_contexts/*"
 
   NewCops: enable
 
@@ -51,6 +52,10 @@ Style/DoubleNegation:
 Style/PerlBackrefs:
   Enabled: false
 
+Style/OpenStructUse:
+  Exclude:
+    - "spec/**/*"
+
 ########################################
 # Lint Cops
 
@@ -66,6 +71,10 @@ Security/Eval:
 ########################################
 # Metrics Cops
 
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+
 Metrics/MethodLength:
   CountComments: false # count full line comments?
   Max: 30
@@ -77,7 +86,7 @@ Metrics/AbcSize:
   Enabled: false
 
 ########################################
-# Metrics Cops
+# Naming Cops
 
 Naming/FileName:
   Enabled: false

data/.ruby-version

@@ -1 +1 @@
-3.0.2
+3.4.8

data/CHANGELOG

@@ -1,3 +1,20 @@
+*1.2.0* (February 17, 2026)
+
+* Add Dockerfile for containerized data generation without requiring a local Ruby installation
+* Add docker-entrypoint.sh with COUNTRY environment variable support and input validation
+* Add .dockerignore to keep Docker build context lean
+
+*1.1.0* (February 14, 2026)
+
+* Fix state abbreviation uniqueness: state lookups are now scoped by country, allowing the same abbreviation (e.g., "NY") in different countries
+* Update state and state_name indexes to include country_id for cross-country uniqueness
+* Synthesize state entries from country data for countries without state/province subdivisions
+* Add logging for silent failure cascade: warn when countries, states, counties, or zipcodes are skipped due to missing lookups
+* Narrow rescue SQLite3::ConstraintException to only swallow UNIQUE violations; re-raise NOT NULL, FOREIGN KEY, and CHECK constraint errors
+* Add comprehensive RSpec test suite with cross-country integration tests
+* Upgrade to Ruby 3.4.8 and fix rubyzip 3.x API compatibility
+* Update README to remove stale rake task references
+
 *1.0.6* (September 30, 2025)
 
 * Bump rexml from 3.3.9 to 3.4.2

data/CLAUDE.md

@@ -0,0 +1,89 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+A Ruby gem that downloads postal/zipcode data from GeoNames.org, processes it via an ETL pipeline, and outputs an SQLite3 database and optional CSV files. Supports single-country or all-countries processing.
+
+## Commands
+
+```bash
+# Install dependencies (vendored to vendor/bundle, binstubs in stubs/)
+bundle install
+
+# Run all tests
+bundle exec rspec
+
+# Run a single test file
+bundle exec rspec spec/path/to/file_spec.rb
+
+# Run a specific test by line number
+bundle exec rspec spec/path/to/file_spec.rb:42
+
+# Lint
+bundle exec rubocop
+
+# Lint with auto-correct
+bundle exec rubocop -a
+
+# Version bumping (do on develop branch, not master)
+bundle exec rake version:bump_patch
+bundle exec rake version:bump_minor
+bundle exec rake version:bump_major
+
+# Build and install gem
+bundle exec rake build
+bundle exec rake install
+
+# Release gem
+bundle exec rake release
+```
+
+## Architecture
+
+The gem follows an ETL (Extract, Transform, Load) pattern using the Kiba gem:
+
+1. **Extract**: `DataSource` downloads zip files from GeoNames.org, extracts them, and prepares CSV files with headers
+2. **Source**: `CsvSource` (Kiba source) feeds rows from the prepared CSV into the pipeline
+3. **Load**: Four Kiba destination table classes write rows into an in-memory SQLite database
+
+### Key Flow
+
+`bin/free_zipcode_data` → `Runner#start` → `DataSource#download` → `DataSource#datafile` (extract zip + add CSV headers) → `SqliteRam` (in-memory DB) → `ETL::FreeZipcodeDataJob` (Kiba pipeline) → `SqliteRam#save_to_disk`
+
+### Core Classes
+
+- **`FreeZipcodeData::Runner`** - CLI entry point; parses args via Optimist, orchestrates the full pipeline
+- **`FreeZipcodeData::DataSource`** - Downloads and extracts GeoNames zip files, prepares CSV with headers
+- **`SqliteRam`** - Wraps SQLite3; works entirely in-memory then saves to disk via `SQLite3::Backup`
+- **`FreeZipcodeData::DbTable`** - Base class for all table classes; provides progress bar, SQL helpers, and country lookup from `country_lookup_table.yml`
+- **`FreeZipcodeData::CountryTable`/`StateTable`/`CountyTable`/`ZipcodeTable`** - Kiba destinations; each has `build` (creates schema + indexes) and `write` (inserts rows, swallows duplicate constraint violations)
+- **`ETL::FreeZipcodeDataJob`** - Configures the Kiba pipeline with one source and four destinations
+- **`CsvSource`** - Kiba-compatible CSV reader
+
+### Singletons
+
+`Options` and `Logger` are singletons (via Ruby's `Singleton` module). `Runner` has an `.instance` convenience class method (returns `new` each time, not cached).
+
+## Configuration
+
+- `.ruby-version`: 3.4.8
+- Bundle path: `vendor/bundle` (binstubs in `stubs/`)
+- Environment: `APP_ENV` controls environment (`test`, `development`)
+- Config file: `~/.free_zipcode_data.yml` (overridable via `FZD_CONFIG_FILE` env var; uses `spec/fixtures/` version in test)
+
+## Rubocop
+
+Key style settings (`.rubocop.yml`):
+- Target Ruby 3.4
+- Max line length: 110
+- Max method length: 30 lines
+- `Style/ClassVars`, `Style/Documentation`, `Metrics/AbcSize`, `Lint/SuppressedException` disabled
+- `vendor/` and `stubs/` excluded
+
+## Git Workflow
+
+- `master` is the release branch
+- `develop` is the development branch
+- Version bumps should happen on `develop`, then merge to `master` before `rake release`

data/Dockerfile

@@ -0,0 +1,21 @@
+FROM ruby:3.4-slim
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends build-essential git pkg-config && \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY Gemfile Gemfile.lock free_zipcode_data.gemspec .ruby-version ./
+COPY lib/free_zipcode_data/version.rb lib/free_zipcode_data/version.rb
+RUN git init && git add . && \
+    bundle config set --local without development && \
+    bundle install
+
+COPY . .
+RUN git add .
+
+ENV COUNTRY=""
+VOLUME /output
+
+ENTRYPOINT ["./docker-entrypoint.sh"]

data/Gemfile

@@ -4,3 +4,13 @@ source 'https://rubygems.org'
 git_source(:github) { |repo| "https://github.com/#{repo}.git" }
 
 gemspec
+
+group :development do
+  gem 'bundler'
+  gem 'pry-nav', '~> 0.2'
+  gem 'rake', '~> 13.0'
+  gem 'rspec', '~> 3.7'
+  gem 'rubocop'
+  gem 'ruby-prof', '~> 0.17'
+  gem 'simplecov', '~> 0.16'
+end

data/Gemfile.lock

@@ -1,9 +1,11 @@
 PATH
   remote: .
   specs:
-    free_zipcode_data (1.0.6)
+    free_zipcode_data (1.2.0)
       colored (~> 1.2)
+      csv
       kiba (~> 4.0)
+      logger
       optimist (~> 3.0)
       ruby-progressbar (~> 1.9)
       rubyzip (>= 1.2.2)
@@ -12,63 +14,75 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.2)
+    ast (2.4.3)
     coderay (1.1.3)
     colored (1.2)
-    diff-lcs (1.4.4)
-    docile (1.4.0)
+    csv (3.3.5)
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    json (2.18.1)
     kiba (4.0.0)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
     method_source (0.9.2)
     mini_portile2 (2.8.9)
     optimist (3.2.1)
-    parallel (1.21.0)
-    parser (3.0.2.0)
+    parallel (1.27.0)
+    parser (3.3.10.1)
       ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
     pry (0.12.2)
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
     pry-nav (0.3.0)
       pry (>= 0.9.10, < 0.13.0)
-    rainbow (3.0.0)
-    rake (13.0.6)
-    regexp_parser (2.1.1)
-    rexml (3.4.2)
-    rspec (3.10.0)
-      rspec-core (~> 3.10.0)
-      rspec-expectations (~> 3.10.0)
-      rspec-mocks (~> 3.10.0)
-    rspec-core (3.10.1)
-      rspec-support (~> 3.10.0)
-    rspec-expectations (3.10.1)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    regexp_parser (2.11.3)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.10.0)
-    rspec-mocks (3.10.2)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.7)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.10.0)
-    rspec-support (3.10.3)
-    rubocop (1.22.3)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.84.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
       parallel (~> 1.10)
-      parser (>= 3.0.0.0)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml
-      rubocop-ast (>= 1.12.0, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.12.0)
-      parser (>= 3.0.1.1)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
     ruby-prof (0.18.0)
-    ruby-progressbar (1.11.0)
-    rubyzip (3.1.1)
-    simplecov (0.21.2)
+    ruby-progressbar (1.13.0)
+    rubyzip (3.2.2)
+    simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.12.3)
-    simplecov_json_formatter (0.1.3)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
     sqlite3 (1.7.3)
       mini_portile2 (~> 2.8.0)
-    unicode-display_width (2.1.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
 
 PLATFORMS
   ruby
@@ -84,4 +98,4 @@ DEPENDENCIES
   simplecov (~> 0.16)
 
 BUNDLED WITH
-   2.2.22
+   2.6.9

data/README.md

@@ -6,11 +6,11 @@ This project is an automated solution for retrieving and collating US and worldw
 
 ## History
 
-In 2011, we originally pulled down all the US census data we could find, parsed it and exported it into 3 .csv files. Later, we wrote 3 rake tasks to automate this process.
+In 2011, we originally pulled down all the US census data we could find, parsed it and exported it into 3 .csv files.
 
 In 2017 we began using [GeoNames](http://www.geonames.org) data, which is licensed under Creative Commons. We are grateful to [GeoNames](http://www.geonames.org) for sharing, and urge you to [visit their site](http://www.geonames.org) and support their work.
 
-In 2018 we refactored the project and made it into a Ruby gem with a command-line executable for automating this process.
+In 2018 we refactored the project and made it into a Ruby gem with a unified command-line executable (`free_zipcode_data`) that handles downloading, processing, and database generation in a single step.
 
 ## What's Included
 
@@ -22,7 +22,7 @@ See the GeoNames [readme.txt](http://download.geonames.org/export/zip/readme.txt
 
 ## Usage
 
-First, you need to install Ruby and Rubygems. Though that is not a difficult task, it is beyond the scope of this README. A search engine of your choice will help discover how to do this.  Once you have done that:
+First, you need to install Ruby 3.4+ and Rubygems. Though that is not a difficult task, it is beyond the scope of this README. A search engine of your choice will help discover how to do this.  Once you have done that:
 
 ```bash
 $ gem install free_zipcode_data
@@ -61,8 +61,6 @@ $ free_zipcode_data --work-dir /tmp/work_dir --country US --generate-files
 $ free_zipcode_data --work-dir /tmp/work_dir --generate-files
 ```
 
-The rake tasks cascade, from the bottom up. So if you run `rake data:populate_db`, it will automatically call `rake data:build` if the .csv files are missing, which will call `rake data:download` if the .zip files are missing.
-
 ## SQLite3 Database
 
 The executable will generate an SQLite3 database in the specified directory `--work-dir` but it will not generate the `.csv` files by default. Specify `--generate-files` if you want those as well.
@@ -107,6 +105,41 @@ create table zipcodes (
 
 Both `lat` and `lon`, geocodes, are populated for each zipcode record.
 
+## Docker
+
+If you prefer not to install Ruby locally, you can use Docker to generate the database. You only need [Docker](https://docs.docker.com/get-docker/) installed.
+
+### Build the image
+
+```bash
+$ git clone https://github.com/midwire/free_zipcode_data.git
+$ cd free_zipcode_data
+$ docker build -t free_zipcode_data .
+```
+
+### Generate data
+
+Use the `COUNTRY` environment variable to specify a 2-letter country code. Omit it to process all available countries.
+
+**Single country (e.g., US):**
+
+```bash
+$ docker run --rm -v $(pwd)/output:/output -e COUNTRY=US free_zipcode_data
+```
+
+**All countries:**
+
+```bash
+$ docker run --rm -v $(pwd)/output:/output free_zipcode_data
+```
+
+The following files will be written to the `./output/` directory on your host:
+
+* `free_zipcode_data.sqlite3` - SQLite database with countries, states, counties, and zipcodes tables
+* `countries.csv`, `states.csv`, `counties.csv`, `zipcodes.csv` - CSV exports of each table
+
+Look up supported country codes at [GeoNames](http://download.geonames.org/export/zip/).
+
 ## Data License
 
 The zipcode data is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a>, carried forward from [GeoNames](http://www.geonames.org).<br />

data/Rakefile

@@ -4,7 +4,7 @@ require 'rubygems'
 require 'bundler/setup'
 
 require 'rake'
-Dir['lib/tasks/**/*.rake'].sort.each { |ext| load ext }
+Dir['lib/tasks/**/*.rake'].each { |ext| load ext }
 
 # Install rubygem tasks
 Bundler::GemHelper.install_tasks

data/docker-entrypoint.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+args=(--work-dir /output --generate-files --clobber)
+
+if [ -n "${COUNTRY:-}" ]; then
+  if [[ ! "$COUNTRY" =~ ^[A-Z]{2}$ ]]; then
+    echo "Error: COUNTRY must be a 2-letter uppercase code (e.g., US, AD)" >&2
+    exit 1
+  fi
+  args+=(--country "$COUNTRY")
+fi
+
+exec bundle exec ruby bin/free_zipcode_data "${args[@]}"

data/free_zipcode_data.gemspec

@@ -23,18 +23,12 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler'
-  spec.add_development_dependency 'pry-nav', '~> 0.2'
-  spec.add_development_dependency 'rake', '~> 13.0'
-  spec.add_development_dependency 'rspec', '~> 3.7'
-  spec.add_development_dependency 'rubocop'
-  spec.add_development_dependency 'ruby-prof', '~> 0.17'
-  spec.add_development_dependency 'simplecov', '~> 0.16'
-
-  spec.add_runtime_dependency 'colored', '~> 1.2'
-  spec.add_runtime_dependency 'kiba', '~> 4.0'
-  spec.add_runtime_dependency 'optimist', '~> 3.0'
-  spec.add_runtime_dependency 'ruby-progressbar', '~> 1.9'
-  spec.add_runtime_dependency 'rubyzip', '>= 1.2.2'
-  spec.add_runtime_dependency 'sqlite3', '~> 1.3'
+  spec.add_dependency 'colored', '~> 1.2'
+  spec.add_dependency 'csv'
+  spec.add_dependency 'kiba', '~> 4.0'
+  spec.add_dependency 'logger'
+  spec.add_dependency 'optimist', '~> 3.0'
+  spec.add_dependency 'ruby-progressbar', '~> 1.9'
+  spec.add_dependency 'rubyzip', '>= 1.2.2'
+  spec.add_dependency 'sqlite3', '~> 1.3'
 end

data/lib/etl/common.rb

@@ -16,6 +16,7 @@ end
 def limit(count)
   count = Integer(count || -1)
   return if count == -1
+
   transform do |row|
     @counter ||= 0
     @counter += 1

data/lib/etl/csv_source.rb

@@ -14,10 +14,10 @@ class CsvSource
 
   def each
     CSV.open(filename,
-      col_sep: delimeter,
-      headers: headers,
-      header_converters: :symbol,
-      quote_char: quote_char) do |csv|
+             col_sep: delimeter,
+             headers: headers,
+             header_converters: :symbol,
+             quote_char: quote_char) do |csv|
       csv.each do |row|
         yield(row.to_hash)
       end

data/lib/free_zipcode_data/country_table.rb

@@ -25,6 +25,10 @@ module FreeZipcodeData
 
     def write(row)
       country_hash = country_lookup_table[row[:country]]
+      unless country_hash
+        warn_once("Skipping unknown country '#{row[:country]}': not in country_lookup_table")
+        return update_progress
+      end
 
       sql = <<-SQL
         INSERT INTO countries (alpha2, alpha3, iso, name)
@@ -36,8 +40,12 @@ module FreeZipcodeData
 
       begin
         database.execute(sql)
-      rescue SQLite3::ConstraintException
-        # Swallow duplicates
+      rescue SQLite3::ConstraintException => e
+        unless e.message.include?('UNIQUE')
+          raise "Please file an issue at #{ISSUE_URL}: [#{e}] -> SQL: [#{sql}]"
+        end
+      rescue StandardError => e
+        raise "Please file an issue at #{ISSUE_URL}: [#{e}] -> SQL: [#{sql}]"
       end
 
       update_progress

data/lib/free_zipcode_data/county_table.rb

@@ -26,8 +26,14 @@ module FreeZipcodeData
     def write(row)
       return nil unless row[:county]
 
-      state_id = get_state_id(row[:short_state], row[:state])
-      return nil unless state_id
+      state_id = get_state_id(row[:country], row[:short_state], row[:state])
+      unless state_id
+        logger.verbose(
+          "Skipping county '#{row[:county]}': no state found for " \
+          "abbr='#{row[:short_state]}', country='#{row[:country]}'"
+        )
+        return nil
+      end
 
       sql = <<-SQL
         INSERT INTO counties (state_id, abbr, name)
@@ -39,10 +45,12 @@ module FreeZipcodeData
 
       begin
         database.execute(sql)
-      rescue SQLite3::ConstraintException
-        # swallow duplicates
-      rescue StandardError => err
-        raise "Please file an issue at #{ISSUE_URL}: [#{err}] -> SQL: [#{sql}]"
+      rescue SQLite3::ConstraintException => e
+        unless e.message.include?('UNIQUE')
+          raise "Please file an issue at #{ISSUE_URL}: [#{e}] -> SQL: [#{sql}]"
+        end
+      rescue StandardError => e
+        raise "Please file an issue at #{ISSUE_URL}: [#{e}] -> SQL: [#{sql}]"
       end
 
       update_progress

data/lib/free_zipcode_data/data_source.rb

@@ -56,11 +56,11 @@ module FreeZipcodeData
               if options[:clobber]
                 Zip.on_exists_proc = true
                 Logger.instance.verbose("Extracting: #{zipfile}...")
-                entry.extract(country_file)
+                entry.extract(destination_directory: options.work_dir)
               end
             else
               Logger.instance.verbose("Extracting: #{zipfile}...")
-              entry.extract(country_file)
+              entry.extract(destination_directory: options.work_dir)
             end
             break
           end