free_zipcode_data 1.0.6 → 1.2.0

data/spec/free_zipcode_data/country_table_spec.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'free_zipcode_data/country_table'
+
+RSpec.describe FreeZipcodeData::CountryTable do
+  let(:db) { create_test_database(line_count: 5) }
+  let(:table) { described_class.new(database: db, tablename: 'countries') }
+
+  before { table.build }
+
+  describe '#build' do
+    it 'creates the countries table' do
+      tables = db.execute("SELECT name FROM sqlite_master WHERE type='table' AND name='countries'")
+      expect(tables.length).to eq(1)
+    end
+
+    it 'creates the unique alpha2 index' do
+      indexes = db.execute("SELECT name FROM sqlite_master WHERE type='index' AND tbl_name='countries'")
+      index_names = indexes.map(&:first)
+      expect(index_names).to include('unique_country_alpha2')
+    end
+
+    it 'creates columns for alpha2, alpha3, iso, and name' do
+      columns = db.execute("PRAGMA table_info('countries')").map { |c| c[1] }
+      expect(columns).to include('alpha2', 'alpha3', 'iso', 'name')
+    end
+  end
+
+  describe '#write' do
+    it 'inserts a country row using the lookup table' do
+      table.write({ country: 'US' })
+      rows = db.execute('SELECT alpha2, alpha3, name FROM countries')
+      expect(rows.length).to eq(1)
+      expect(rows[0]).to eq(['US', 'USA', 'United States of America'])
+    end
+
+    it 'inserts multiple different countries' do
+      table.write({ country: 'US' })
+      table.write({ country: 'CA' })
+      table.write({ country: 'GB' })
+      rows = db.execute('SELECT alpha2 FROM countries ORDER BY alpha2')
+      expect(rows.flatten).to eq(%w[CA GB US])
+    end
+
+    it 'silently ignores duplicate country codes' do
+      table.write({ country: 'US' })
+      expect { table.write({ country: 'US' }) }.not_to raise_error
+      rows = db.execute('SELECT COUNT(*) FROM countries')
+      expect(rows[0][0]).to eq(1)
+    end
+  end
+end

data/spec/free_zipcode_data/county_table_spec.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'free_zipcode_data/county_table'
+
+RSpec.describe FreeZipcodeData::CountyTable do
+  let(:db) { create_test_database(line_count: 5) }
+  let(:table) { described_class.new(database: db, tablename: 'counties') }
+
+  before do
+    seed_countries(db)
+    seed_states(db)
+    table.build
+  end
+
+  describe '#build' do
+    it 'creates the counties table' do
+      tables = db.execute("SELECT name FROM sqlite_master WHERE type='table' AND name='counties'")
+      expect(tables.length).to eq(1)
+    end
+
+    it 'creates the unique_county index' do
+      indexes = db.execute("SELECT name FROM sqlite_master WHERE type='index' AND tbl_name='counties'")
+      index_names = indexes.map(&:first)
+      expect(index_names).to include('unique_county')
+    end
+
+    it 'creates columns for state_id, abbr, name, and county_seat' do
+      columns = db.execute("PRAGMA table_info('counties')").map { |c| c[1] }
+      expect(columns).to include('state_id', 'abbr', 'name', 'county_seat')
+    end
+  end
+
+  describe '#write' do
+    it 'inserts a county row' do
+      table.write({ country: 'US', county: 'Cook', short_county: '031', short_state: 'IL',
+                    state: 'Illinois' })
+      rows = db.execute('SELECT name, abbr FROM counties')
+      expect(rows.length).to eq(1)
+      expect(rows[0]).to eq(%w[Cook 031])
+    end
+
+    it 'links the county to its state' do
+      table.write({ country: 'US', county: 'Cook', short_county: '031', short_state: 'IL',
+                    state: 'Illinois' })
+      state_id = db.execute("SELECT id FROM states WHERE abbr = 'IL'")[0][0]
+      county_state_id = db.execute('SELECT state_id FROM counties')[0][0]
+      expect(county_state_id).to eq(state_id)
+    end
+
+    it 'returns nil and skips when county is nil' do
+      result = table.write({ country: 'US', county: nil, short_county: nil, short_state: 'IL',
+                             state: 'Illinois' })
+      expect(result).to be_nil
+      rows = db.execute('SELECT COUNT(*) FROM counties')
+      expect(rows[0][0]).to eq(0)
+    end
+
+    it 'returns nil when state cannot be found' do
+      result = table.write({ country: 'US', county: 'Unknown', short_county: '999', short_state: 'ZZ',
+                             state: 'Nonexistent' })
+      expect(result).to be_nil
+      rows = db.execute('SELECT COUNT(*) FROM counties')
+      expect(rows[0][0]).to eq(0)
+    end
+
+    it 'silently ignores duplicate county entries' do
+      table.write({ country: 'US', county: 'Cook', short_county: '031', short_state: 'IL',
+                    state: 'Illinois' })
+      expect do
+        table.write({ country: 'US', county: 'Cook', short_county: '031', short_state: 'IL',
+                      state: 'Illinois' })
+      end.not_to raise_error
+      rows = db.execute('SELECT COUNT(*) FROM counties')
+      expect(rows[0][0]).to eq(1)
+    end
+
+    it 'handles county names with single quotes' do
+      table.write({ country: 'US', county: "Prince George's", short_county: '033', short_state: 'NY',
+                    state: 'New York' })
+      rows = db.execute('SELECT name FROM counties')
+      expect(rows[0][0]).to eq("Prince George's")
+    end
+  end
+end

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