free_zipcode_data 1.0.6 → 1.1.0

data/spec/free_zipcode_data/data_source_spec.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'free_zipcode_data/data_source'
+
+RSpec.describe FreeZipcodeData::DataSource do
+  let(:work_dir) { Dir.mktmpdir('datasource_test') }
+  let(:options) do
+    OpenStruct.new(
+      work_dir: work_dir,
+      clobber: false,
+      country: 'US',
+      verbose: false
+    )
+  end
+  let(:options_instance) { FreeZipcodeData::Options.instance }
+
+  before do
+    options_instance.initialize_hash(options)
+  end
+
+  after do
+    FileUtils.rm_rf(work_dir)
+  end
+
+  describe '#initialize' do
+    it 'stores the country' do
+      ds = described_class.new('US')
+      expect(ds.country).to eq('US')
+    end
+
+    it 'defaults country to nil' do
+      ds = described_class.new
+      expect(ds.country).to be_nil
+    end
+  end
+
+  describe '#download' do
+    let(:datasource) { described_class.new('US') }
+    let(:fixture_zip) { File.read(File.join(FreeZipcodeData.root, 'spec', 'fixtures', 'US.zip')) }
+
+    it 'downloads and saves the zip file' do
+      uri_object = instance_double(URI::HTTP)
+      allow(URI).to receive(:parse).and_return(uri_object)
+      allow(uri_object).to receive(:open).and_yield(StringIO.new(fixture_zip))
+
+      datasource.download
+
+      expect(File.exist?(File.join(work_dir, 'US.zip'))).to be true
+    end
+
+    it 'skips download if the file already exists and clobber is false' do
+      FileUtils.touch(File.join(work_dir, 'US.zip'))
+
+      expect(URI).not_to receive(:parse)
+      datasource.download
+    end
+
+    it 'redownloads if clobber is true' do
+      FileUtils.touch(File.join(work_dir, 'US.zip'))
+      options_instance.initialize_hash(OpenStruct.new(work_dir: work_dir, clobber: true, country: 'US',
+                                                      verbose: false))
+
+      uri_object = instance_double(URI::HTTP)
+      allow(URI).to receive(:parse).and_return(uri_object)
+      allow(uri_object).to receive(:open).and_yield(StringIO.new(fixture_zip))
+
+      datasource.download
+
+      expect(File.size(File.join(work_dir, 'US.zip'))).to be > 0
+    end
+  end
+
+  describe '#datafile' do
+    let(:datasource) { described_class.new('US') }
+
+    before do
+      fixture_dir = File.join(FreeZipcodeData.root, 'spec', 'fixtures')
+      # Copy fixture zip and pre-extracted text to work_dir
+      FileUtils.cp(File.join(fixture_dir, 'US.zip'), File.join(work_dir, 'US.zip'))
+      FileUtils.cp(File.join(fixture_dir, 'US.txt'), File.join(work_dir, 'US.txt'))
+    end
+
+    it 'returns a CSV file path with headers prepended' do
+      result = datasource.datafile
+      expect(result).to end_with('.csv')
+      expect(File.exist?(result)).to be true
+    end
+
+    it 'prepends headers to the extracted data' do
+      result = datasource.datafile
+      first_line = File.open(result, &:readline)
+      expect(first_line).to include('COUNTRY')
+      expect(first_line).to include('POSTAL_CODE')
+      expect(first_line).to include('LATITUDE')
+    end
+
+    it 'contains the original data rows' do
+      result = datasource.datafile
+      lines = File.readlines(result)
+      # header + 5 data rows
+      expect(lines.length).to eq(6)
+    end
+
+    it 'does not re-extract if CSV already exists and clobber is false' do
+      first = datasource.datafile
+      mtime = File.mtime(first)
+      sleep(0.1)
+      # Create a new instance to avoid memoization
+      ds2 = described_class.new('US')
+      second = ds2.datafile
+      expect(File.mtime(second)).to eq(mtime)
+    end
+  end
+
+  describe 'zipfile naming' do
+    it 'uses country code for single country' do
+      ds = described_class.new('US')
+      expect(ds.send(:zipfile)).to eq('US.zip')
+    end
+
+    it 'uppercases the country code' do
+      ds = described_class.new('us')
+      expect(ds.send(:zipfile)).to eq('US.zip')
+    end
+
+    it 'uses allCountries when no country specified' do
+      ds = described_class.new(nil)
+      expect(ds.send(:zipfile)).to eq('allCountries.zip')
+    end
+  end
+end

data/spec/free_zipcode_data/db_table_spec.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require 'free_zipcode_data/db_table'
+
+RSpec.describe FreeZipcodeData::DbTable do
+  let(:db) { create_test_database(line_count: 5) }
+
+  # DbTable is abstract - we need a concrete subclass to test it
+  let(:concrete_class) do
+    Class.new(described_class) do
+      def build; end
+    end
+  end
+
+  let(:table) { concrete_class.new(database: db, tablename: 'test_table') }
+
+  describe '#initialize' do
+    it 'stores the database and tablename' do
+      expect(table.database).to eq(db)
+      expect(table.tablename).to eq('test_table')
+    end
+  end
+
+  describe '#update_progress' do
+    it 'increments the progress bar without error' do
+      expect { table.update_progress }.not_to raise_error
+    end
+  end
+
+  describe 'private #escape_single_quotes' do
+    it 'escapes single quotes for SQL safety' do
+      result = table.send(:escape_single_quotes, "O'Brien")
+      expect(result).to eq("O''Brien")
+    end
+
+    it 'handles nil gracefully' do
+      result = table.send(:escape_single_quotes, nil)
+      expect(result).to eq('')
+    end
+
+    it 'handles strings without quotes' do
+      result = table.send(:escape_single_quotes, 'Chicago')
+      expect(result).to eq('Chicago')
+    end
+  end
+
+  describe 'private #country_lookup_table' do
+    it 'loads the YAML lookup table' do
+      lookup = table.send(:country_lookup_table)
+      expect(lookup).to be_a(Hash)
+      expect(lookup['US'][:name]).to eq('United States of America')
+    end
+  end
+
+  describe 'private #select_first' do
+    it 'returns the first column of the first row' do
+      result = table.send(:select_first, "SELECT value FROM meta WHERE name = 'line_count'")
+      expect(result).to eq('5')
+    end
+
+    it 'returns nil when no rows match' do
+      result = table.send(:select_first, "SELECT value FROM meta WHERE name = 'nonexistent'")
+      expect(result).to be_nil
+    end
+
+    it 'raises with issue URL on SQL error' do
+      expect do
+        table.send(:select_first, 'SELECT * FROM nonexistent_table')
+      end.to raise_error(/Please file an issue/)
+    end
+  end
+
+  context 'with seeded countries and states' do
+    before do
+      seed_countries(db)
+      seed_states(db)
+    end
+
+    describe 'private #get_country_id' do
+      it 'returns the country ID for a known alpha2 code' do
+        id = table.send(:get_country_id, 'US')
+        expect(id).to be_a(Integer)
+      end
+
+      it 'returns nil for an unknown country' do
+        id = table.send(:get_country_id, 'ZZ')
+        expect(id).to be_nil
+      end
+    end
+
+    describe 'private #get_state_id' do
+      it 'finds a state by exact match (abbr + name + country)' do
+        expected_id = db.execute("SELECT id FROM states WHERE abbr = 'NY'")[0][0]
+        id = table.send(:get_state_id, 'US', 'NY', 'New York')
+        expect(id).to eq(expected_id)
+      end
+
+      it 'falls back to abbr + country when name does not match' do
+        expected_id = db.execute("SELECT id FROM states WHERE abbr = 'NY'")[0][0]
+        id = table.send(:get_state_id, 'US', 'NY', 'Wrong Name')
+        expect(id).to eq(expected_id)
+      end
+
+      it 'falls back to name + country when abbr does not match' do
+        expected_id = db.execute("SELECT id FROM states WHERE name = 'New York'")[0][0]
+        id = table.send(:get_state_id, 'US', 'XX', 'New York')
+        expect(id).to eq(expected_id)
+      end
+
+      it 'returns nil for an unknown state' do
+        id = table.send(:get_state_id, 'US', 'ZZ', 'Nonexistent')
+        expect(id).to be_nil
+      end
+
+      it 'returns nil when country is nil' do
+        id = table.send(:get_state_id, nil, 'NY', 'New York')
+        expect(id).to be_nil
+      end
+
+      it 'scopes lookup by country' do
+        # Seed a Canadian state with the same abbr as a US state
+        ca_state_table = FreeZipcodeData::StateTable.new(database: db, tablename: 'states')
+        ca_state_table.write({ country: 'CA', short_state: 'NY', state: 'Northern Yukon' })
+
+        us_id = table.send(:get_state_id, 'US', 'NY', 'New York')
+        ca_id = table.send(:get_state_id, 'CA', 'NY', 'Northern Yukon')
+
+        expect(us_id).to be_a(Integer)
+        expect(ca_id).to be_a(Integer)
+        expect(us_id).not_to eq(ca_id)
+      end
+
+      it 'returns nil when all three fallbacks fail' do
+        id = table.send(:get_state_id, 'GB', 'ZZ', 'Nonexistent')
+        expect(id).to be_nil
+      end
+    end
+  end
+
+  context 'with seeded counties' do
+    before do
+      seed_countries(db)
+      seed_states(db)
+      seed_counties(db)
+    end
+
+    describe 'private #get_county_id' do
+      it 'returns the county ID for a known county name' do
+        id = table.send(:get_county_id, 'Cook')
+        expect(id).to be_a(Integer)
+      end
+
+      it 'returns nil for nil county' do
+        id = table.send(:get_county_id, nil)
+        expect(id).to be_nil
+      end
+
+      it 'returns nil for an unknown county' do
+        id = table.send(:get_county_id, 'Nonexistent County')
+        expect(id).to be_nil
+      end
+    end
+  end
+end

data/spec/free_zipcode_data/logger_spec.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+RSpec.describe FreeZipcodeData::Logger do
+  let(:logger) { described_class.instance }
+  let(:string_io) { StringIO.new }
+  let(:test_provider) { Logger.new(string_io) }
+
+  before do
+    logger.log_provider = test_provider
+  end
+
+  after do
+    # Restore default logger
+    logger.log_provider = Logger.new($stdout)
+  end
+
+  describe '#info' do
+    it 'delegates to the log provider' do
+      logger.info('test message')
+      expect(string_io.string).to include('test message')
+    end
+  end
+
+  describe '#log_exception' do
+    it 'logs exception class, message, and backtrace' do
+      error = begin
+        raise StandardError, 'something broke'
+      rescue StandardError => e
+        e
+      end
+
+      logger.log_exception(error)
+      output = string_io.string
+      expect(output).to include('EXCEPTION')
+      expect(output).to include('StandardError')
+      expect(output).to include('something broke')
+    end
+
+    it 'includes data hash when provided' do
+      error = begin
+        raise StandardError, 'oops'
+      rescue StandardError => e
+        e
+      end
+
+      logger.log_exception(error, { user_id: 42 })
+      expect(string_io.string).to include('user_id')
+    end
+  end
+
+  describe '#verbose' do
+    let(:options) { FreeZipcodeData::Options.instance }
+
+    it 'logs when verbose option is true' do
+      options.initialize_hash(OpenStruct.new(verbose: true))
+      logger.verbose('verbose message')
+      expect(string_io.string).to include('verbose message')
+    end
+
+    it 'does not log when verbose option is false' do
+      options.initialize_hash(OpenStruct.new(verbose: false))
+      logger.verbose('should not appear')
+      expect(string_io.string).not_to include('should not appear')
+    end
+  end
+
+  describe '#respond_to?' do
+    it 'returns true for methods the log provider responds to' do
+      expect(logger.respond_to?(:info)).to be true
+      expect(logger.respond_to?(:warn)).to be true
+      expect(logger.respond_to?(:error)).to be true
+    end
+
+    it 'returns false for unknown methods' do
+      expect(logger.respond_to?(:nonexistent_method)).to be false
+    end
+  end
+end

data/spec/free_zipcode_data/options_spec.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+RSpec.describe FreeZipcodeData::Options do
+  let(:options) { described_class.instance }
+
+  after do
+    # Reset singleton state
+    options.initialize_hash({})
+  end
+
+  describe '#initialize_hash' do
+    it 'stores the given hash' do
+      options.initialize_hash({ work_dir: '/tmp/claude/test', country: 'US' })
+      expect(options.hash).to include(work_dir: '/tmp/claude/test', country: 'US')
+    end
+  end
+
+  describe '#[]' do
+    it 'returns the value for the given key' do
+      options.initialize_hash({ country: 'GB' })
+      expect(options[:country]).to eq('GB')
+    end
+
+    it 'returns nil for missing keys' do
+      options.initialize_hash({})
+      expect(options[:nonexistent]).to be_nil
+    end
+  end
+
+  describe '#hash' do
+    it 'returns the full options hash' do
+      data = { work_dir: '/tmp/claude/test', verbose: true }
+      options.initialize_hash(data)
+      expect(options.hash).to eq(data)
+    end
+  end
+end

data/spec/free_zipcode_data/runner_spec.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'free_zipcode_data/runner'
+
+RSpec.describe FreeZipcodeData::Runner do
+  let(:work_dir) { Dir.mktmpdir('runner_test') }
+  let(:fixture_zip) { File.join(FreeZipcodeData.root, 'spec', 'fixtures', 'US.zip') }
+  let(:string_io) { StringIO.new }
+
+  after do
+    FileUtils.rm_rf(work_dir)
+  end
+
+  describe '.instance' do
+    it 'returns a Runner instance' do
+      expect(described_class.instance).to be_a(described_class)
+    end
+  end
+
+  describe '#initialize' do
+    it 'sets up a logger' do
+      runner = described_class.new
+      expect(runner.logger).to eq(FreeZipcodeData::Logger.instance)
+    end
+  end
+
+  describe '#start' do
+    let(:runner) { described_class.new }
+
+    before do
+      # Suppress logger output
+      runner.logger.log_provider = Logger.new(string_io)
+
+      # Copy fixture zip and pre-extracted text into work_dir
+      fixture_dir = File.join(FreeZipcodeData.root, 'spec', 'fixtures')
+      FileUtils.mkdir_p(work_dir)
+      FileUtils.cp(File.join(fixture_dir, 'US.zip'), File.join(work_dir, 'US.zip'))
+      FileUtils.cp(File.join(fixture_dir, 'US.txt'), File.join(work_dir, 'US.txt'))
+
+      # Stub ARGV to provide required CLI args
+      stub_const('ARGV', [
+                   '--work-dir', work_dir,
+                   '--country', 'US',
+                   '--generate-files'
+                 ])
+    end
+
+    it 'creates an SQLite database in the work directory' do
+      runner.start
+      expect(File.exist?(File.join(work_dir, 'free_zipcode_data.sqlite3'))).to be true
+    end
+
+    it 'generates CSV files when --generate-files is specified' do
+      runner.start
+      %w[countries states counties zipcodes].each do |table|
+        expect(File.exist?(File.join(work_dir, "#{table}.csv"))).to be true
+      end
+    end
+
+    it 'populates the SQLite database with data' do
+      runner.start
+      db = SQLite3::Database.new(File.join(work_dir, 'free_zipcode_data.sqlite3'))
+      country_count = db.execute('SELECT COUNT(*) FROM countries')[0][0]
+      zipcode_count = db.execute('SELECT COUNT(*) FROM zipcodes')[0][0]
+      expect(country_count).to be >= 1
+      expect(zipcode_count).to be >= 1
+      db.close
+    end
+
+    it 'sets the options on the runner' do
+      runner.start
+      expect(runner.options).not_to be_nil
+      expect(runner.options[:work_dir]).to eq(work_dir)
+    end
+
+    context 'without --generate-files' do
+      before do
+        stub_const('ARGV', [
+                     '--work-dir', work_dir,
+                     '--country', 'US'
+                   ])
+      end
+
+      it 'creates the database but not CSV files' do
+        runner.start
+        expect(File.exist?(File.join(work_dir, 'free_zipcode_data.sqlite3'))).to be true
+        expect(File.exist?(File.join(work_dir, 'countries.csv'))).to be false
+      end
+    end
+  end
+end

data/spec/free_zipcode_data/sqlite_ram_spec.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+require 'free_zipcode_data/sqlite_ram'
+
+RSpec.describe SqliteRam do
+  let(:tmpdir) { Dir.mktmpdir('sqlite_ram_test') }
+  let(:db_path) { File.join(tmpdir, 'test_db.sqlite3') }
+  let(:sqlite_ram) { described_class.new(db_path) }
+
+  after do
+    FileUtils.rm_rf(tmpdir)
+  end
+
+  describe '#initialize' do
+    it 'creates an in-memory database connection' do
+      expect(sqlite_ram.conn).to be_a(SQLite3::Database)
+    end
+
+    it 'stores the filename' do
+      expect(sqlite_ram.filename).to eq(db_path)
+    end
+  end
+
+  describe '#save_to_disk' do
+    it 'persists in-memory data to the file database' do
+      sqlite_ram.conn.execute('CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)')
+      sqlite_ram.conn.execute("INSERT INTO test (name) VALUES ('hello')")
+      sqlite_ram.save_to_disk
+
+      file_db = SQLite3::Database.new(db_path)
+      rows = file_db.execute('SELECT name FROM test')
+      expect(rows).to eq([['hello']])
+      file_db.close
+    end
+  end
+
+  describe '#dump_tables' do
+    it 'exports each table to a CSV file in the given directory' do
+      sqlite_ram.conn.execute('CREATE TABLE widgets (id INTEGER PRIMARY KEY, name TEXT, weight REAL)')
+      sqlite_ram.conn.execute("INSERT INTO widgets (name, weight) VALUES ('gear', 1.5)")
+      sqlite_ram.conn.execute("INSERT INTO widgets (name, weight) VALUES ('bolt', 0.3)")
+
+      sqlite_ram.dump_tables(tmpdir)
+
+      csv_path = File.join(tmpdir, 'widgets.csv')
+      expect(File.exist?(csv_path)).to be true
+
+      csv = CSV.read(csv_path)
+      expect(csv[0]).to eq(%w[id name weight])
+      expect(csv.length).to eq(3) # header + 2 rows
+    end
+
+    it 'exports multiple tables' do
+      sqlite_ram.conn.execute('CREATE TABLE a (id INTEGER PRIMARY KEY)')
+      sqlite_ram.conn.execute('CREATE TABLE b (id INTEGER PRIMARY KEY)')
+
+      sqlite_ram.dump_tables(tmpdir)
+
+      expect(File.exist?(File.join(tmpdir, 'a.csv'))).to be true
+      expect(File.exist?(File.join(tmpdir, 'b.csv'))).to be true
+    end
+  end
+end

data/spec/free_zipcode_data/state_table_spec.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'free_zipcode_data/state_table'
+
+RSpec.describe FreeZipcodeData::StateTable do
+  let(:db) { create_test_database(line_count: 5) }
+  let(:table) { described_class.new(database: db, tablename: 'states') }
+
+  before do
+    seed_countries(db)
+    table.build
+  end
+
+  describe '#build' do
+    it 'creates the states table' do
+      tables = db.execute("SELECT name FROM sqlite_master WHERE type='table' AND name='states'")
+      expect(tables.length).to eq(1)
+    end
+
+    it 'creates the unique_state index' do
+      indexes = db.execute("SELECT name FROM sqlite_master WHERE type='index' AND tbl_name='states'")
+      index_names = indexes.map(&:first)
+      expect(index_names).to include('unique_state')
+    end
+
+    it 'creates the state_name index' do
+      indexes = db.execute("SELECT name FROM sqlite_master WHERE type='index' AND tbl_name='states'")
+      index_names = indexes.map(&:first)
+      expect(index_names).to include('state_name')
+    end
+
+    it 'creates columns for country_id, abbr, and name' do
+      columns = db.execute("PRAGMA table_info('states')").map { |c| c[1] }
+      expect(columns).to include('country_id', 'abbr', 'name')
+    end
+  end
+
+  describe '#write' do
+    it 'inserts a state row' do
+      table.write({ country: 'US', short_state: 'NY', state: 'New York' })
+      rows = db.execute('SELECT abbr, name FROM states')
+      expect(rows.length).to eq(1)
+      expect(rows[0]).to eq(['NY', 'New York'])
+    end
+
+    it 'links the state to its country' do
+      table.write({ country: 'US', short_state: 'NY', state: 'New York' })
+      country_id = db.execute("SELECT id FROM countries WHERE alpha2 = 'US'")[0][0]
+      state_country_id = db.execute('SELECT country_id FROM states')[0][0]
+      expect(state_country_id).to eq(country_id)
+    end
+
+    it 'creates a state from country lookup when short_state is nil' do
+      row = { country: 'US', short_state: nil, state: 'Unknown' }
+      table.write(row)
+      rows = db.execute("SELECT abbr, name FROM states WHERE abbr = 'US'")
+      expect(rows.length).to eq(1)
+      expect(rows[0]).to eq(['US', 'United States of America'])
+      # Verify row mutation for downstream Kiba destinations
+      expect(row[:short_state]).to eq('US')
+      expect(row[:state]).to eq('United States of America')
+    end
+
+    it 'creates a state from country lookup when short_state is empty' do
+      table.write({ country: 'US', short_state: '', state: 'Unknown' })
+      rows = db.execute("SELECT abbr, name FROM states WHERE abbr = 'US'")
+      expect(rows.length).to eq(1)
+      expect(rows[0]).to eq(['US', 'United States of America'])
+    end
+
+    it 'returns nil when short_state is nil and country is unknown' do
+      result = table.write({ country: 'ZZ', short_state: nil, state: 'Unknown' })
+      expect(result).to be_nil
+      rows = db.execute('SELECT COUNT(*) FROM states')
+      expect(rows[0][0]).to eq(0)
+    end
+
+    it 'returns nil when country is not in the countries table' do
+      result = table.write({ country: 'DE', short_state: 'BY', state: 'Bavaria' })
+      expect(result).to be_nil
+      rows = db.execute('SELECT COUNT(*) FROM states')
+      expect(rows[0][0]).to eq(0)
+    end
+
+    it 'silently ignores duplicate state entries' do
+      table.write({ country: 'US', short_state: 'NY', state: 'New York' })
+      expect { table.write({ country: 'US', short_state: 'NY', state: 'New York' }) }.not_to raise_error
+      rows = db.execute('SELECT COUNT(*) FROM states')
+      expect(rows[0][0]).to eq(1)
+    end
+
+    it 'handles the Marshall Islands edge case' do
+      table.write({ country: 'US', short_state: 'MH', state: nil })
+      rows = db.execute("SELECT name FROM states WHERE abbr = 'MH'")
+      expect(rows[0][0]).to eq('Marshall Islands')
+    end
+
+    it 'handles state names with single quotes' do
+      # Some international state names can have apostrophes
+      table.write({ country: 'US', short_state: 'TX', state: "Cote d'Ivoire" })
+      rows = db.execute("SELECT name FROM states WHERE abbr = 'TX'")
+      expect(rows[0][0]).to eq("Cote d'Ivoire")
+    end
+
+    it 'allows states with the same name in different countries' do
+      table.write({ country: 'US', short_state: 'BC', state: 'British Columbia' })
+      table.write({ country: 'CA', short_state: 'BC', state: 'British Columbia' })
+      rows = db.execute("SELECT COUNT(*) FROM states WHERE name = 'British Columbia'")
+      expect(rows[0][0]).to eq(2)
+    end
+  end
+end