jp_address_complement 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17438b03576a1b31a50ee4ed00413a2da5ccd8e2187c3ccb1b4f60f5f9a8c0df
-  data.tar.gz: 1efaf00afc7166bdb9b6bfcdde8128ea9e7d9682d5500c1096d9d8eb7e166ed9
+  metadata.gz: 5ac0fd79d7ab6a6cfead9398aa3907ccfcbfe6766e59a3653b768035f057e5ce
+  data.tar.gz: be6413cd0b12304bf00259f3a8bbacf68051bdaa6f7d74eaf54718550c4f0a9e
 SHA512:
-  metadata.gz: dc70f4d677374348176ae4a724aee2fba171fc101cde7c2c091a2c8d32d594a6ac51d7575c16fedf5ae9e7babda75f1fd575e7072f2062beb7105c45798e5ef0
-  data.tar.gz: dab79d95277591fec2a31775b9b436397900ed7cd889f9db5016008286efcdfb68021d91771573f26e858fbde6abf36b691b6ed7e566cbe14ab14d5a65f7b449
+  metadata.gz: 7ab89ad98dc9510ba4a9524dc4683211ecb39562b8a91b669164c4e2c7da82d515ebaa9a9a780fd5c385ca8c228a1ac0b0673e21678deeea9b9e3f6271ce836a
+  data.tar.gz: bc901f201de85ffd2aedca0613c07dd988f478927ff91f2220e9195f5587fba695a78ea8c16ca25971e64c3186dca69ba5ca15f70776fb0de3ba4333ca9a84f9

data/CHANGELOG.md

@@ -1,25 +1,36 @@
 ## [Unreleased]
 
-### Changed
+## [0.3.0] - 2026-03-02
+
+### Security
 
-- **CSV インポート（003: 消えたレコード削除）**
-  - `JpAddressComplement::Importers::CsvImporter#import` の戻り値を **Integer から `ImportResult`（Data.define :upserted, :deleted）に変更**（破壊的変更）
-  - フルインポート時に、今回のCSVに存在しない住所レコードをストアから削除するようにした
-  - 空CSV（有効行0件）の場合はインポートを拒否し、`JpAddressComplement::ImportError` を発生させる
-  - Rake タスク `jp_address_complement:import` の完了メッセージを「インポート完了: upsert N 件, 削除 M 件」形式に変更
+- **Zip Slip 脆弱性の修正**: 解凍先パスの検証を強化し、Zip Slip 攻撃を防止。あわせて `Dir.chdir` によるスレッド安全性の問題を解消
 
 ### Added
 
-- **都道府県コード変換・住所逆引き（004）**
-  - `JpAddressComplement.prefecture_name_from_code(code)` — 都道府県コード（2桁）から正式名称を返す（該当なしは nil）
-  - `JpAddressComplement.prefecture_code_from_name(name)` — 都道府県の正式名称から2桁コードを返す（該当なしは nil）
-  - `JpAddressComplement.search_postal_codes_by_address(pref:, city:, town: nil)` — 都道府県・市区町村・町域から郵便番号候補を逆引き（該当なし・入力不十分時は []）
+- 町域なしの住所も `valid_combination?` で一致とみなすように変更（テスト追加）
+
+### Changed
+
+- **ActiveSupport 依存の廃止**: `blank?` をネイティブ Ruby に置換
+- **upsert_batch の改善**: N+1 DELETE を Arel バッチ削除に変更し、SQLite の式木深度上限エラーに対応（`DELETE_CHUNK_SIZE` 導入）
+- **COL_* 定数の整理**: KenAll モジュールに集約し重複を解消
+- README: `search_postal_codes_by_address` の戻り値を正しく記載
+
+### Fixed
+
+- RuboCop 違反の修正（Metrics/AbcSize 含む）および RBS シグネチャの更新
+
+## [0.2.0] - 2026-03-02
+
+### Changed
 
-- RBS type annotations and Steep type checking (see [specs/002-rbs-type-annotations](../specs/002-rbs-type-annotations/))
-  - Public API and internal methods annotated with rbs-inline
-  - `sig/` and `sig/manual/` for type definitions; `AddressRecord` hand-defined in `sig/manual/address_record.rbs`
-  - Rake tasks: `rake rbs:generate` (generate RBS from annotations), `rake steep` (type check)
-  - CI runs `bundle exec rake steep`; type errors fail the build
+- **Active Record をオプショナルに変更**
+  - gemspec: `activerecord` / `railties` を runtime 依存から削除し、development 依存に移動
+  - デフォルトリポジトリ・`base_record_class`: Gemfile のみで未 require の場合に備え、require を試してから利用するよう変更（`defined?` 判定を廃止）
+  - Railtie: 同様に `require 'rails'` を試してから読み込むよう変更
+  - `default_repository`: LoadError 時に利用者向けメッセージで `JpAddressComplement::Error` を発生
+  - README: 必要環境・インストール手順に利用者側の対応を追記
 
 ## [0.1.0] - 2026-02-22
 

data/README.md

@@ -26,8 +26,7 @@
 ## 必要環境
 
 - Ruby 3.2 以上
-- Rails 7.1 以上
-- ActiveRecord 利用を前提としています
+- **デフォルトの DB 利用（ActiveRecord）を使う場合のみ**: Rails 7.0 以上および `activerecord` gem（Rails アプリでは通常含まれる）。使わない場合は不要です。
 
 ## インストール
 
@@ -39,13 +38,24 @@
 gem 'jp_address_complement'
 ```
 
+**デフォルトの ActiveRecord リポジトリを使う場合（DB に郵便番号テーブルを置く場合）**  
+本 gem は `activerecord` を必須依存にしていません。Rails アプリでは `gem 'rails'` に含まれるため追加不要です。Rails を使わずに ActiveRecord だけ使う場合は、利用者側で `Gemfile` に `activerecord` を追加してください。
+
+```ruby
+gem 'jp_address_complement'
+gem 'activerecord', '>= 7.0'   # デフォルトリポジトリを使う場合のみ
+```
+
+**CSV リポジトリや自前リポジトリだけ使う場合**  
+`JpAddressComplement.configure { |c| c.repository = ... }` でリポジトリを設定すれば、`activerecord` は不要です。gem の追加だけで利用できます。
+
 Bundler を使わない場合:
 
 ```bash
 gem install jp_address_complement
 ```
 
-### 2. テーブルの作成
+### 2. テーブルの作成（デフォルトの ActiveRecord リポジトリを使う場合）
 
 郵便番号データを格納するマイグレーションを生成し、マイグレートします。
 
@@ -54,7 +64,7 @@ rails g jp_address_complement:install
 rails db:migrate
 ```
 
-### 3. 住所データのインポート
+### 3. 住所データのインポート（デフォルトの ActiveRecord リポジトリを使う場合）
 
 日本郵便の KEN_ALL 形式 CSV（UTF-8 版 `utf_ken_all.csv`）をインポートする必要があります。
 
@@ -125,7 +135,7 @@ records = JpAddressComplement.search_by_postal_code_prefix('1000')
 
 ### 郵便番号と住所の整合性チェック
 
-「この郵便番号とこの住所の組み合わせは正しいか？」を判定します。フォームのバリデーションに利用できます。
+「この郵便番号とこの住所の組み合わせは正しいか？」を判定します。フォームのバリデーションに利用できます。町域まで含む場合は町域まで、市区町村までしか含まれていない場合は市区町村までのチェックとなります。
 
 ```ruby
 JpAddressComplement.valid_combination?('1000001', '東京都千代田区千代田')
@@ -177,12 +187,16 @@ JpAddressComplement.prefecture_code_from_name('東京都')
 都道府県・市区町村・町域を指定して、対応する郵便番号の一覧を取得します。
 
 ```ruby
-codes = JpAddressComplement.search_postal_codes_by_address(
+results = JpAddressComplement.search_postal_codes_by_address(
   pref: '東京都',
   city: '千代田区',
   town: '千代田'
 )
-# => ["1000001"] など、該当する郵便番号の配列
+# => [["1000001", #<JpAddressComplement::AddressRecord postal_code="1000001", pref="東京都", city="千代田区", town="千代田", ...>]]
+
+# 郵便番号のみが必要な場合
+results.map(&:first)
+# => ["1000001"]
 ```
 
 `town` は省略可能です。その場合は都道府県＋市区町村で検索されます。

data/examples/rails/jp_address_complement_demo/Gemfile.lock

@@ -1,10 +1,8 @@
 PATH
   remote: ../../..
   specs:
-    jp_address_complement (0.1.0)
-      activerecord (>= 7.0)
+    jp_address_complement (0.3.0)
       csv (>= 3.0)
-      railties (>= 7.0)
       rubyzip (>= 2.3)
 
 GEM

data/lib/jp_address_complement/importers/csv_importer.rb

@@ -4,6 +4,7 @@
 require 'csv'
 require_relative '../address_record'
 require_relative '../models/postal_code'
+require_relative '../ken_all'
 
 module JpAddressComplement
   module Importers
@@ -15,20 +16,16 @@ module JpAddressComplement
     # UTF-8 版 KEN_ALL（utf_ken_all.csv）を読み込み、jp_address_complement_postal_codes テーブルに upsert する
     # UTF-8 形式の CSV を前提として処理する
     class CsvImporter
-      BATCH_SIZE = 1000 #: Integer
+      include KenAll
+
+      # バッチ削除・ユニークキーとして使うカラム群
+      KEY_COLUMNS = %i[postal_code pref_code city town kana_pref kana_city kana_town].freeze #: Array[Symbol]
 
-      # 列インデックス（KEN_ALL.CSV 形式）
-      COL_PREF_CODE = 0 #: Integer
-      COL_POSTAL_CODE = 2 #: Integer
-      COL_KANA_PREF = 3 #: Integer
-      COL_KANA_CITY = 4 #: Integer
-      COL_KANA_TOWN = 5 #: Integer
-      COL_PREF = 6 #: Integer
-      COL_CITY = 7 #: Integer
-      COL_TOWN = 8 #: Integer
-      COL_IS_PARTIAL = 9 #: Integer
-      COL_HAS_ALIAS = 12 #: Integer
-      COL_IS_LARGE_OFFICE = 13 #: Integer
+      # SQLite のデフォルト式木深度制限（1000）対策。
+      # reduce(:or) で N 件 OR 結合すると深さ ≈ N + 6 になるため、500 件に収める（深さ ≈ 506）。
+      DELETE_CHUNK_SIZE = 500 #: Integer
+
+      BATCH_SIZE = 1000 #: Integer
 
       # @rbs (String csv_path) -> void
       def initialize(csv_path)
@@ -108,22 +105,24 @@ module JpAddressComplement
       # @rbs (Array[Hash[Symbol, untyped]] batch) -> void
       def upsert_batch(batch)
         PostalCode.transaction do
-          batch.each do |record|
-            PostalCode.where(
-              postal_code: record[:postal_code],
-              pref_code: record[:pref_code],
-              city: record[:city],
-              town: record[:town],
-              kana_pref: record[:kana_pref],
-              kana_city: record[:kana_city],
-              kana_town: record[:kana_town]
-            ).delete_all
-          end
-
+          batch_delete(batch)
           PostalCode.upsert_all(batch)
         end
       end
 
+      # バッチ内の全レコードを1クエリで一括削除する
+      # Arel を使うことで NULL カラム（town 等）を IS NULL として正しく扱う
+      # @rbs (Array[Hash[Symbol, untyped]] batch) -> void
+      def batch_delete(batch)
+        table = PostalCode.arel_table
+        batch.each_slice(DELETE_CHUNK_SIZE) do |chunk|
+          conditions = chunk.map do |record|
+            KEY_COLUMNS.map { |col| table[col].eq(record[col]) }.reduce(:and)
+          end.reduce(:or)
+          PostalCode.where(conditions).delete_all
+        end
+      end
+
       # 郵便番号・都道府県・市区町村・町域（漢字）が同じでも読み（カナ）が異なれば別レコードとして扱う
       # @rbs (Hash[Symbol, untyped] record) -> Array[String]
       def row_key(record)

data/lib/jp_address_complement/ken_all.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module JpAddressComplement
+  # UTF-8 版 KEN_ALL（utf_ken_all.csv）のフォーマット定数
+  #
+  # CSV の各列インデックスを定義する。include することでクラス内から直接参照できる。
+  #
+  # 参考: https://www.post.japanpost.jp/zipcode/dl/readme.html
+  module KenAll
+    # 列インデックス（KEN_ALL.CSV 形式）
+    COL_PREF_CODE = 0 # : Integer
+    COL_POSTAL_CODE = 2 # : Integer
+    COL_KANA_PREF = 3 # : Integer
+    COL_KANA_CITY = 4 # : Integer
+    COL_KANA_TOWN = 5 # : Integer
+    COL_PREF = 6 # : Integer
+    COL_CITY = 7 # : Integer
+    COL_TOWN = 8 # : Integer
+    COL_IS_PARTIAL = 9 # : Integer
+    COL_HAS_ALIAS = 12 # : Integer
+    COL_IS_LARGE_OFFICE = 13 # : Integer
+  end
+end

data/lib/jp_address_complement/ken_all_downloader.rb

@@ -94,21 +94,35 @@ module JpAddressComplement
     def extract_zip_entries(zip_path, tmpdir)
       csv_path = nil
       Zip::File.open(zip_path) do |zip_file|
-        Dir.chdir(tmpdir) do
-          zip_file.each do |entry|
-            name = entry.name.delete_prefix('/')
-            dir = File.dirname(name)
-            FileUtils.mkdir_p(dir) unless dir == '.'
-            # RubyZip::Entry#extract(dest_path = nil) を使い、既存ファイルがあればブロックで上書き許可する。
-            entry.extract(name) { true } # steep:ignore
-            dest = File.join(tmpdir, name)
-            csv_path = dest if entry_csv?(name, dest)
-          end
+        zip_file.each do |entry|
+          dest = safe_extract_dest(tmpdir, entry.name)
+          next if dest.nil? || dest == tmpdir # パストラバーサルの可能性があるエントリはスキップ
+
+          FileUtils.mkdir_p(File.dirname(dest))
+          # RubyZip 3.x: 第1引数は destination_directory 配下への相対パス、
+          # destination_directory: で展開先ディレクトリを指定する。
+          # safe_extract_dest で検証済みの相対パスを渡し、パストラバーサルを多層防御する。
+          relative_path = dest[(tmpdir.length + 1)..]
+          entry.extract(relative_path, destination_directory: tmpdir) { true } # steep:ignore
+          csv_path = dest if entry_csv?(entry.name, dest)
         end
       end
       csv_path
     end
 
+    # ZIP エントリの展開先絶対パスを安全に解決する。
+    # entry_name に含まれる ../ などにより tmpdir の外を指す場合は nil を返す（Zip Slip 対策）。
+    # @rbs (String tmpdir, String entry_name) -> String?
+    def safe_extract_dest(tmpdir, entry_name)
+      # 先頭の / を除去して相対パスとして扱い、File.expand_path で ../ を解決する
+      relative = entry_name.delete_prefix('/')
+      dest = File.expand_path(File.join(tmpdir, relative))
+      # tmpdir 配下に収まるエントリのみ許可する
+      return nil unless dest.start_with?("#{tmpdir}#{File::SEPARATOR}") || dest == tmpdir
+
+      dest
+    end
+
     # @rbs (String entry_name, String dest) -> bool
     def entry_csv?(entry_name, dest)
       File.basename(entry_name) == CSV_FILENAME && File.file?(dest)

data/lib/jp_address_complement/normalizer.rb

@@ -21,7 +21,7 @@ module JpAddressComplement
       # @param code [String, nil] 郵便番号文字列（ハイフン・全角・〒記号を自動除去）
       # @return [String, nil] 正規化後の7桁郵便番号。不正な場合は nil
       def normalize_postal_code(code)
-        return nil if code.blank?
+        return nil if code.nil? || code.strip.empty?
 
         normalized = normalize_string(code)
         return nil unless normalized.match?(DIGIT_ONLY)
@@ -34,7 +34,7 @@ module JpAddressComplement
       # @param prefix [String, nil] 郵便番号の先頭部分（4桁以上）
       # @return [String, nil] 正規化後の数字文字列。4桁未満または不正な場合は nil
       def normalize_prefix(prefix)
-        return nil if prefix.blank?
+        return nil if prefix.nil? || prefix.strip.empty?
 
         normalized = normalize_string(prefix)
         return nil if normalized.empty?

data/lib/jp_address_complement/railtie.rb

@@ -14,6 +14,8 @@ module JpAddressComplement
     end
 
     initializer 'jp_address_complement.setup_repository' do # steep:ignore
+      next unless defined?(ActiveRecord)
+
       require_relative 'repositories/active_record_postal_code_repository'
       require_relative 'models/postal_code'
       JpAddressComplement.configuration.repository ||=

data/lib/jp_address_complement/repositories/active_record_postal_code_repository.rb

@@ -35,11 +35,11 @@ module JpAddressComplement
 
       # @rbs (pref: String?, city: String?, ?town: String?) -> untyped
       def address_relation(pref:, city:, town: nil)
-        return nil if pref.nil? || pref.to_s.strip.empty?
-        return nil if city.nil? || city.to_s.strip.empty?
+        return nil if pref.to_s.strip.empty?
+        return nil if city.to_s.strip.empty?
 
         relation = postal_code_model.where(pref: pref, city: city)
-        return relation if town.blank?
+        return relation if town.to_s.strip.empty?
 
         pattern = "#{escape_like(town.to_s.strip)}%"
         relation.where('town LIKE ?', pattern)

data/lib/jp_address_complement/repositories/csv_postal_code_repository.rb

@@ -5,6 +5,7 @@
 require 'csv'
 require_relative 'postal_code_repository'
 require_relative '../address_record'
+require_relative '../ken_all'
 
 module JpAddressComplement
   module Repositories
@@ -23,18 +24,7 @@ module JpAddressComplement
     #   end
     #
     class CsvPostalCodeRepository < PostalCodeRepository
-      # 列インデックス（KEN_ALL.CSV 形式）
-      COL_PREF_CODE = 0 # : Integer
-      COL_POSTAL_CODE = 2 # : Integer
-      COL_KANA_PREF = 3 # : Integer
-      COL_KANA_CITY = 4 # : Integer
-      COL_KANA_TOWN = 5 # : Integer
-      COL_PREF = 6 # : Integer
-      COL_CITY = 7 # : Integer
-      COL_TOWN = 8 # : Integer
-      COL_IS_PARTIAL = 9 # : Integer
-      COL_HAS_ALIAS = 12 # : Integer
-      COL_IS_LARGE_OFFICE = 13 # : Integer
+      include KenAll
 
       # @rbs (String csv_path) -> void
       # @param csv_path [String] 読み込む KEN_ALL 形式 UTF-8 CSV のパス

data/lib/jp_address_complement/searcher.rb

@@ -76,6 +76,7 @@ module JpAddressComplement
       full = base + town_part
 
       return true if address.include?(full)
+      return true if address == base # 町域なしの住所も許容する
       return false if town_part.empty?
 
       # 日本郵便の CSV は町域に「字」「大字」を含まない。市区町村の直後に「字」「大字」が付いた表記は省略可能なため無視する。

data/lib/jp_address_complement/validators/address_validator.rb

@@ -20,7 +20,8 @@ module JpAddressComplement
       postal_code = record.public_send(postal_code_field)
       address = record.public_send(address_field)
 
-      return if postal_code.blank? || address.blank?
+      return if (postal_code.nil? || postal_code.to_s.strip.empty?) ||
+                (address.nil? || address.to_s.strip.empty?)
 
       return if JpAddressComplement.valid_combination?(postal_code, address)
 

data/lib/jp_address_complement/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module JpAddressComplement
-  VERSION = '0.1.0' #: String
+  VERSION = '0.3.0' #: String
 end

data/lib/jp_address_complement.rb

@@ -9,8 +9,13 @@ require_relative 'jp_address_complement/repositories/postal_code_repository'
 require_relative 'jp_address_complement/searcher'
 require_relative 'jp_address_complement/prefecture'
 
-# Rails 環境でのみ Railtie をロード
-require_relative 'jp_address_complement/railtie' if defined?(Rails)
+# Rails が利用可能な場合のみ Railtie をロード（Gemfile に指定されていても require 前だと defined?(Rails) が false になり得るため、require を試す）
+begin
+  require 'rails'
+  require_relative 'jp_address_complement/railtie'
+rescue LoadError
+  # Rails が利用できない場合は Railtie をスキップ
+end
 
 module JpAddressComplement
   class Error < StandardError; end
@@ -31,10 +36,19 @@ module JpAddressComplement
       @configuration ||= Configuration.new
     end
 
-    # PostalCode モデルの継承元。未設定時は ActiveRecord::Base。configuration.postal_code_model_base に委譲する。
+    # PostalCode モデルの継承元。未設定時は ActiveRecord::Base（activerecord gem が利用可能な場合）。
+    # Gemfile に指定されていても require 前だと defined? が false になり得るため、未ロード時は require を試す。
     # @rbs () -> Class
     def base_record_class
-      configuration.postal_code_model_base || ActiveRecord::Base
+      base = configuration.postal_code_model_base
+      return base if base
+
+      require 'active_record'
+      ActiveRecord::Base
+    rescue LoadError => e
+      raise Error,
+            'ActiveRecord is not available. Add gem "activerecord" to your Gemfile, or set ' \
+            "JpAddressComplement.configuration.postal_code_model_base. (#{e.message})"
     end
 
     # @rbs (Class) -> void
@@ -124,6 +138,10 @@ module JpAddressComplement
       require_relative 'jp_address_complement/repositories/active_record_postal_code_repository'
       require_relative 'jp_address_complement/models/postal_code'
       Repositories::ActiveRecordPostalCodeRepository.new
+    rescue LoadError => e
+      raise Error,
+            'ActiveRecord is not loaded. Add gem "activerecord" to your Gemfile to use the default repository, ' \
+            "or set JpAddressComplement.configuration.repository to your own implementation. (#{e.message})"
     end
   end
 end

data/sig/generated/jp_address_complement/importers/csv_importer.rbs

@@ -21,30 +21,16 @@ module JpAddressComplement
     # UTF-8 版 KEN_ALL（utf_ken_all.csv）を読み込み、jp_address_complement_postal_codes テーブルに upsert する
     # UTF-8 形式の CSV を前提として処理する
     class CsvImporter
-      BATCH_SIZE: Integer
-
-      # 列インデックス（KEN_ALL.CSV 形式）
-      COL_PREF_CODE: Integer
-
-      COL_POSTAL_CODE: Integer
-
-      COL_KANA_PREF: Integer
-
-      COL_KANA_CITY: Integer
-
-      COL_KANA_TOWN: Integer
+      include KenAll
 
-      COL_PREF: Integer
+      # バッチ削除・ユニークキーとして使うカラム群
+      KEY_COLUMNS: Array[Symbol]
 
-      COL_CITY: Integer
+      # SQLite のデフォルト式木深度制限（1000）対策。
+      # reduce(:or) で N 件 OR 結合すると深さ ≈ N + 6 になるため、500 件に収める（深さ ≈ 506）。
+      DELETE_CHUNK_SIZE: Integer
 
-      COL_TOWN: Integer
-
-      COL_IS_PARTIAL: Integer
-
-      COL_HAS_ALIAS: Integer
-
-      COL_IS_LARGE_OFFICE: Integer
+      BATCH_SIZE: Integer
 
       # @rbs (String csv_path) -> void
       def initialize: (String csv_path) -> void
@@ -66,6 +52,11 @@ module JpAddressComplement
       # @rbs (Array[Hash[Symbol, untyped]] batch) -> void
       def upsert_batch: (Array[Hash[Symbol, untyped]] batch) -> void
 
+      # バッチ内の全レコードを1クエリで一括削除する
+      # Arel を使うことで NULL カラム（town 等）を IS NULL として正しく扱う
+      # @rbs (Array[Hash[Symbol, untyped]] batch) -> void
+      def batch_delete: (Array[Hash[Symbol, untyped]] batch) -> void
+
       # 郵便番号・都道府県・市区町村・町域（漢字）が同じでも読み（カナ）が異なれば別レコードとして扱う
       # @rbs (Hash[Symbol, untyped] record) -> Array[String]
       def row_key: (Hash[Symbol, untyped] record) -> Array[String]

data/sig/generated/jp_address_complement/ken_all.rbs

@@ -0,0 +1,33 @@
+# Generated from lib/jp_address_complement/ken_all.rb with RBS::Inline
+
+module JpAddressComplement
+  # UTF-8 版 KEN_ALL（utf_ken_all.csv）のフォーマット定数
+  #
+  # CSV の各列インデックスを定義する。include することでクラス内から直接参照できる。
+  #
+  # 参考: https://www.post.japanpost.jp/zipcode/dl/readme.html
+  module KenAll
+    # 列インデックス（KEN_ALL.CSV 形式）
+    COL_PREF_CODE: ::Integer
+
+    COL_POSTAL_CODE: ::Integer
+
+    COL_KANA_PREF: ::Integer
+
+    COL_KANA_CITY: ::Integer
+
+    COL_KANA_TOWN: ::Integer
+
+    COL_PREF: ::Integer
+
+    COL_CITY: ::Integer
+
+    COL_TOWN: ::Integer
+
+    COL_IS_PARTIAL: ::Integer
+
+    COL_HAS_ALIAS: ::Integer
+
+    COL_IS_LARGE_OFFICE: ::Integer
+  end
+end

data/sig/generated/jp_address_complement/ken_all_downloader.rbs

@@ -40,6 +40,11 @@ module JpAddressComplement
     # @rbs (String zip_path, String tmpdir) -> String?
     def extract_zip_entries: (String zip_path, String tmpdir) -> String?
 
+    # ZIP エントリの展開先絶対パスを安全に解決する。
+    # entry_name に含まれる ../ などにより tmpdir の外を指す場合は nil を返す（Zip Slip 対策）。
+    # @rbs (String tmpdir, String entry_name) -> String?
+    def safe_extract_dest: (String tmpdir, String entry_name) -> String?
+
     # @rbs (String entry_name, String dest) -> bool
     def entry_csv?: (String entry_name, String dest) -> bool
 

data/sig/generated/jp_address_complement/repositories/csv_postal_code_repository.rbs

@@ -16,28 +16,7 @@ module JpAddressComplement
     #     c.repository = JpAddressComplement::Repositories::CsvPostalCodeRepository.new('/path/to/utf_ken_all.csv')
     #   end
     class CsvPostalCodeRepository < PostalCodeRepository
-      # 列インデックス（KEN_ALL.CSV 形式）
-      COL_PREF_CODE: ::Integer
-
-      COL_POSTAL_CODE: ::Integer
-
-      COL_KANA_PREF: ::Integer
-
-      COL_KANA_CITY: ::Integer
-
-      COL_KANA_TOWN: ::Integer
-
-      COL_PREF: ::Integer
-
-      COL_CITY: ::Integer
-
-      COL_TOWN: ::Integer
-
-      COL_IS_PARTIAL: ::Integer
-
-      COL_HAS_ALIAS: ::Integer
-
-      COL_IS_LARGE_OFFICE: ::Integer
+      include KenAll
 
       # @rbs (String csv_path) -> void
       # @param csv_path [String] 読み込む KEN_ALL 形式 UTF-8 CSV のパス

data/sig/generated/jp_address_complement.rbs

@@ -17,7 +17,8 @@ module JpAddressComplement
   # @return [Configuration]
   def self.configuration: () -> Configuration
 
-  # PostalCode モデルの継承元。未設定時は ActiveRecord::Base。configuration.postal_code_model_base に委譲する。
+  # PostalCode モデルの継承元。未設定時は ActiveRecord::Base（activerecord gem が利用可能な場合）。
+  # Gemfile に指定されていても require 前だと defined? が false になり得るため、未ロード時は require を試す。
   # @rbs () -> Class
   def self.base_record_class: () -> Class
 

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: jp_address_complement
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - naokirin
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-28 00:00:00.000000000 Z
+date: 2026-03-01 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: activerecord
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '7.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: csv
   requirement: !ruby/object:Gem::Requirement
@@ -39,33 +25,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
-  name: railties
+  name: rubyzip
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '2.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '2.3'
 - !ruby/object:Gem::Dependency
-  name: rubyzip
+  name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.3'
-  type: :runtime
+        version: '7.0'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.3'
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: generator_spec
   requirement: !ruby/object:Gem::Requirement
@@ -108,6 +94,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -355,6 +355,7 @@ files:
 - lib/jp_address_complement/address_record.rb
 - lib/jp_address_complement/configuration.rb
 - lib/jp_address_complement/importers/csv_importer.rb
+- lib/jp_address_complement/ken_all.rb
 - lib/jp_address_complement/ken_all_downloader.rb
 - lib/jp_address_complement/models/postal_code.rb
 - lib/jp_address_complement/normalizer.rb
@@ -373,6 +374,7 @@ files:
 - sig/generated/jp_address_complement.rbs
 - sig/generated/jp_address_complement/configuration.rbs
 - sig/generated/jp_address_complement/importers/csv_importer.rbs
+- sig/generated/jp_address_complement/ken_all.rbs
 - sig/generated/jp_address_complement/ken_all_downloader.rbs
 - sig/generated/jp_address_complement/normalizer.rbs
 - sig/generated/jp_address_complement/prefecture.rbs