Fix PR review issues: stale docs, error handling, and security concerns

- Update CLAUDE.md with correct Ruby 3.4.8 and rubocop 3.4 target versions
- Fix CLAUDE.md architecture description (Source not Transform, add datafile step, namespaces)
- Remove redundant .freeze from write_version_file to match frozen_string_literal
- Replace Kernel#open with File.read in version.rake
- Add logger gem as runtime dependency (leaving default gems in Ruby 4.0)
- Add StandardError rescue to CountryTable#write and StateTable#write
- Add nil guard for unknown country codes in CountryTable#write
- Fix .rubocop.yml section header (Naming Cops, not Metrics Cops)

Author: midwire

.rubocop.yml

@@ -86,7 +86,7 @@ Metrics/AbcSize:
   Enabled: false
 
 ########################################
-# Metrics Cops
+# Naming Cops
 
 Naming/FileName:
   Enabled: false

CLAUDE.md

@@ -45,38 +45,38 @@ bundle exec rake release
 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. **Transform**: `CsvSource` (Kiba source) reads rows from the prepared CSV
+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` → `SqliteRam` (in-memory DB) → `ETL::FreeZipcodeDataJob` (Kiba pipeline) → `SqliteRam#save_to_disk`
+`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`
-- **`CountryTable`/`StateTable`/`CountyTable`/`ZipcodeTable`** - Kiba destinations; each has `build` (creates schema + indexes) and `write` (inserts rows, swallows duplicate constraint violations)
+- **`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` uses a manual singleton pattern.
+`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.0.2
+- `.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 2.7
+- Target Ruby 3.4
 - Max line length: 110
 - Max method length: 30 lines
 - `Style/ClassVars`, `Style/Documentation`, `Metrics/AbcSize`, `Lint/SuppressedException` disabled

Gemfile.lock

@@ -5,6 +5,7 @@ PATH
       colored (~> 1.2)
       csv
       kiba (~> 4.0)
+      logger
       optimist (~> 3.0)
       ruby-progressbar (~> 1.9)
       rubyzip (>= 1.2.2)
@@ -23,6 +24,7 @@ GEM
     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)

free_zipcode_data.gemspec

@@ -26,6 +26,7 @@ Gem::Specification.new do |spec|
   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'

lib/free_zipcode_data/country_table.rb

@@ -25,6 +25,7 @@ def build
 
     def write(row)
       country_hash = country_lookup_table[row[:country]]
+      return update_progress unless country_hash
 
       sql = <<-SQL
         INSERT INTO countries (alpha2, alpha3, iso, name)
@@ -38,6 +39,8 @@ def write(row)
         database.execute(sql)
       rescue SQLite3::ConstraintException
         # Swallow duplicates
+      rescue StandardError => e
+        raise "Please file an issue at #{ISSUE_URL}: [#{e}] -> SQL: [#{sql}]"
       end
 
       update_progress

lib/free_zipcode_data/state_table.rb

@@ -44,6 +44,8 @@ def write(row)
         database.execute(sql)
       rescue SQLite3::ConstraintException
         # Swallow duplicates
+      rescue StandardError => e
+        raise "Please file an issue at #{ISSUE_URL}: [#{e}] -> SQL: [#{sql}]"
       end
 
       update_progress

lib/tasks/version.rake

@@ -91,7 +91,7 @@ namespace :version do
 
   def write_version_file(version_array)
     version = version_array.join('.')
-    new_version = %(  VERSION = '#{version}'.freeze)
+    new_version = %(  VERSION = '#{version}')
     lines = File.readlines(version_file_path)
     File.open(version_file_path, 'w') do |f|
       lines.each do |line|
@@ -106,7 +106,7 @@ namespace :version do
 
   def update_readme_version_strings
     version_string = read_version.join('.')
-    readme = open('README.md').read
+    readme = File.read('README.md')
     regex = /^\*\*Version: [0-9.]+\*\*$/i
     return nil unless readme =~ regex