jp_address_complement 0.1.0

data/lib/jp_address_complement/searcher.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative 'normalizer'
+require_relative 'repositories/postal_code_repository'
+
+module JpAddressComplement
+  # コア検索ロジック
+  # Repository を注入して使用することで ActiveRecord への直接依存を排除する
+  class Searcher
+    # @rbs (Repositories::PostalCodeRepository repository) -> void
+    def initialize(repository)
+      @repository = repository
+    end
+
+    # 7桁郵便番号から住所レコードを検索する
+    # @rbs (String? code) -> Array[AddressRecord]
+    # @param code [String, nil] 郵便番号
+    # @return [Array<AddressRecord>]
+    def search_by_postal_code(code)
+      normalized = Normalizer.normalize_postal_code(code)
+      return [] if normalized.nil?
+
+      @repository.find_by_code(normalized)
+    end
+
+    # 郵便番号プレフィックスから住所候補を検索する（4桁以上）
+    # @rbs (String? prefix) -> Array[AddressRecord]
+    # @param prefix [String, nil] 郵便番号の先頭部分
+    # @return [Array<AddressRecord>]
+    def search_by_postal_code_prefix(prefix)
+      normalized = Normalizer.normalize_prefix(prefix)
+      return [] if normalized.nil?
+
+      @repository.find_by_prefix(normalized)
+    end
+
+    # 郵便番号と住所文字列の整合性を検証する
+    # 日本郵便の utf_ken_all.csv は町域に「字」「大字」を含まないため、
+    # 市区町村の直後に「字」「大字」が付いた住所（省略可能な表記）も一致とみなす。
+    # @rbs (String? postal_code, String? address) -> bool
+    # @param postal_code [String, nil] 郵便番号
+    # @param address [String, nil] 住所文字列
+    # @return [Boolean]
+    def valid_combination?(postal_code, address)
+      return false if postal_code.nil? || address.nil?
+
+      normalized = Normalizer.normalize_postal_code(postal_code)
+      return false if normalized.nil?
+
+      records = @repository.find_by_code(normalized)
+      return false if records.empty?
+
+      records.any? { |record| address_matches_record?(address, record) }
+    end
+
+    # 都道府県・市区町村・町域から郵便番号候補を取得する（逆引き）。町域は前方一致。
+    # @rbs (pref: String?, city: String?, ?town: String?) -> Array[[String, AddressRecord]]
+    # @param pref [String] 都道府県名（正式名称）
+    # @param city [String] 市区町村名
+    # @param town [String, nil] 町域名。省略時は都道府県＋市区町村のみ。指定時は前方一致で候補を返す
+    # @return [Array<[String, AddressRecord]>] [郵便番号, AddressRecord] の配列。該当なし・入力不十分時は []
+    def search_postal_codes_by_address(pref:, city:, town: nil)
+      return [] if pref.nil? || pref.to_s.strip.empty?
+      return [] if city.nil? || city.to_s.strip.empty?
+
+      records = @repository.find_postal_codes_by_address(pref: pref, city: city, town: town)
+      records.map { |r| [r.postal_code, r] }
+    end
+
+    private
+
+    def address_matches_record?(address, record)
+      base = record.pref + record.city
+      town_part = record.normalized_town.to_s
+      full = base + town_part
+
+      return true if address.include?(full)
+      return false if town_part.empty?
+
+      # 日本郵便の CSV は町域に「字」「大字」を含まない。市区町村の直後に「字」「大字」が付いた表記は省略可能なため無視する。
+      address.include?("#{base}大字#{town_part}") || address.include?("#{base}字#{town_part}")
+    end
+  end
+end

data/lib/jp_address_complement/validators/address_validator.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'active_model'
+
+module JpAddressComplement
+  # ActiveModel::Validator を継承した郵便番号・住所整合性バリデーター
+  #
+  # @example
+  #   class User
+  #     include ActiveModel::Validations
+  #     validates_with JpAddressComplement::AddressValidator,
+  #                    postal_code_field: :postal_code,
+  #                    address_field: :full_address
+  #   end
+  # @rbs inherits ActiveModel::Validator
+  class AddressValidator < ActiveModel::Validator
+    # @rbs (untyped record) -> void
+    def validate(record)
+      postal_code = record.public_send(postal_code_field)
+      address = record.public_send(address_field)
+
+      return if postal_code.blank? || address.blank?
+
+      return if JpAddressComplement.valid_combination?(postal_code, address)
+
+      record.errors.add(address_field, :invalid_combination,
+                        message: 'と郵便番号の組み合わせが正しくありません')
+    end
+
+    private
+
+    def postal_code_field
+      options.fetch(:postal_code_field, :postal_code)
+    end
+
+    def address_field
+      options.fetch(:address_field, :address)
+    end
+  end
+end

data/lib/jp_address_complement/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module JpAddressComplement
+  VERSION = '0.1.0' #: String
+end

data/lib/jp_address_complement.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative 'jp_address_complement/version'
+require_relative 'jp_address_complement/address_record'
+require_relative 'jp_address_complement/normalizer'
+require_relative 'jp_address_complement/configuration'
+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)
+
+module JpAddressComplement
+  class Error < StandardError; end
+  class ImportError < Error; end
+
+  class << self
+    # Gem の設定を行う
+    # @rbs () { (Configuration) -> void } -> void
+    # @yield [Configuration]
+    def configure
+      yield(configuration)
+    end
+
+    # 現在の設定を返す
+    # @rbs () -> Configuration
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # PostalCode モデルの継承元。未設定時は ActiveRecord::Base。configuration.postal_code_model_base に委譲する。
+    # @rbs () -> Class
+    def base_record_class
+      configuration.postal_code_model_base || ActiveRecord::Base
+    end
+
+    # @rbs (Class) -> void
+    def base_record_class=(klass)
+      configuration.postal_code_model_base = klass
+    end
+
+    # PostalCode が参照するテーブル名。未設定時は 'jp_address_complement_postal_codes'。configuration.postal_code_table_name に委譲。
+    # @rbs () -> String
+    def postal_code_table_name
+      configuration.postal_code_table_name || 'jp_address_complement_postal_codes'
+    end
+
+    # @rbs (String) -> void
+    def postal_code_table_name=(name)
+      configuration.postal_code_table_name = name
+    end
+
+    # 設定をリセットする（主にテスト用）
+    # @rbs () -> void
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # 設定されたリポジトリを返す（デフォルトは ActiveRecord 実装）
+    # @rbs () -> Repositories::PostalCodeRepository
+    # @return [Repositories::PostalCodeRepository]
+    def repository
+      configuration.repository ||= default_repository
+    end
+
+    # 7桁郵便番号から住所レコードを検索する
+    # @rbs (String) -> Array[AddressRecord]
+    # @param code [String] 郵便番号（ハイフン・全角・〒 記号を自動正規化）
+    # @return [Array<AddressRecord>]
+    def search_by_postal_code(code)
+      Searcher.new(repository).search_by_postal_code(code)
+    end
+
+    # 郵便番号の先頭4桁以上から住所候補を検索する
+    # @rbs (String) -> Array[AddressRecord]
+    # @param prefix [String] 郵便番号の先頭部分（4桁以上）
+    # @return [Array<AddressRecord>]
+    def search_by_postal_code_prefix(prefix)
+      Searcher.new(repository).search_by_postal_code_prefix(prefix)
+    end
+
+    # 郵便番号と住所文字列の整合性を検証する
+    # @rbs (String, String) -> bool
+    # @param postal_code [String] 郵便番号（自動正規化）
+    # @param address [String] 住所文字列
+    # @return [Boolean]
+    def valid_combination?(postal_code, address)
+      Searcher.new(repository).valid_combination?(postal_code, address)
+    end
+
+    # 都道府県コード（JIS X 0401）から都道府県名を返す
+    # @rbs (String | Integer?) -> String?
+    # @param code [String, Integer, nil] 都道府県コード（01–47）
+    # @return [String, nil] 都道府県名。該当なし時は nil
+    def prefecture_name_from_code(code)
+      Prefecture.name_from_code(code)
+    end
+
+    # 都道府県名（正式名称）から都道府県コードを2桁文字列で返す
+    # @rbs (String?) -> String?
+    # @param name [String, nil] 都道府県の正式名称
+    # @return [String, nil] 2桁のコード（例: "13"）。該当なし時は nil
+    def prefecture_code_from_name(name)
+      Prefecture.code_from_name(name)
+    end
+
+    # 都道府県・市区町村・町域から郵便番号候補を取得する（逆引き）。町域は前方一致。
+    # @rbs (pref: String?, city: String?, ?town: String?) -> Array[[String, AddressRecord]]
+    # @param pref [String] 都道府県名（正式名称）
+    # @param city [String] 市区町村名
+    # @param town [String, nil] 町域名。省略可。指定時は前方一致で候補を返す
+    # @return [Array<[String, AddressRecord]>] [郵便番号, AddressRecord] の配列。該当なし・入力不十分時は []
+    def search_postal_codes_by_address(pref:, city:, town: nil)
+      Searcher.new(repository).search_postal_codes_by_address(pref: pref, city: city, town: town)
+    end
+
+    private
+
+    # @rbs () -> Repositories::ActiveRecordPostalCodeRepository
+    def default_repository
+      require_relative 'jp_address_complement/repositories/active_record_postal_code_repository'
+      require_relative 'jp_address_complement/models/postal_code'
+      Repositories::ActiveRecordPostalCodeRepository.new
+    end
+  end
+end

data/lib/tasks/jp_address_complement.rake

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'jp_address_complement'
+require 'jp_address_complement/importers/csv_importer'
+
+namespace :jp_address_complement do
+  desc 'KEN_ALL.CSV から住所データをインポートする（CSV=<ファイルパス> または DOWNLOAD=1 で公式URLから取得）'
+  task import: :environment do
+    csv_path = resolve_csv_path_for_import
+
+    puts "インポート開始: #{csv_path}"
+    result = JpAddressComplement::Importers::CsvImporter.new(csv_path).import
+    puts "インポート完了: upsert #{result.upserted} 件, 削除 #{result.deleted} 件"
+  end
+end
+
+def resolve_csv_path_for_import
+  if ENV['DOWNLOAD'] == '1'
+    require 'jp_address_complement/ken_all_downloader'
+    url = ENV.fetch('KEN_ALL_ZIP_URL', JpAddressComplement::KenAllDownloader::DEFAULT_URL)
+    puts "ダウンロード中: #{url}"
+    JpAddressComplement::KenAllDownloader.new(url).download_and_extract
+  else
+    csv_path = ENV.fetch('CSV', nil)
+    if csv_path.nil?
+      raise ArgumentError,
+            'CSV 環境変数でファイルパスを指定するか、DOWNLOAD=1 で公式URLから取得してください。' \
+            '例: rake jp_address_complement:import CSV=/path/to/KEN_ALL.CSV または DOWNLOAD=1'
+    end
+    csv_path
+  end
+end

data/rbs_collection.lock.yaml

@@ -0,0 +1,380 @@
+---
+path: ".gem_rbs_collection"
+gems:
+- name: actionpack
+  version: '7.2'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: actionview
+  version: '6.0'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: activemodel
+  version: '7.1'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: activerecord
+  version: '8.0'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: activesupport
+  version: '7.0'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: ast
+  version: '2.4'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: base64
+  version: 0.3.0
+  source:
+    type: rubygems
+- name: bigdecimal
+  version: '4.0'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: cgi
+  version: '0.5'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: concurrent-ruby
+  version: '1.1'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: connection_pool
+  version: '2.4'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: csv
+  version: '3.3'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: date
+  version: '0'
+  source:
+    type: stdlib
+- name: delegate
+  version: '0'
+  source:
+    type: stdlib
+- name: diff-lcs
+  version: '1.5'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: digest
+  version: '0'
+  source:
+    type: stdlib
+- name: erb
+  version: '0'
+  source:
+    type: stdlib
+- name: ffi
+  version: 1.17.3
+  source:
+    type: rubygems
+- name: fileutils
+  version: '0'
+  source:
+    type: stdlib
+- name: forwardable
+  version: '0'
+  source:
+    type: stdlib
+- name: i18n
+  version: '1.10'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: io-console
+  version: '0'
+  source:
+    type: stdlib
+- name: json
+  version: '0'
+  source:
+    type: stdlib
+- name: listen
+  version: '3.9'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: logger
+  version: '0'
+  source:
+    type: stdlib
+- name: minitest
+  version: '5.25'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: monitor
+  version: '0'
+  source:
+    type: stdlib
+- name: mutex_m
+  version: 0.3.0
+  source:
+    type: rubygems
+- name: nokogiri
+  version: '1.11'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: openssl
+  version: '0'
+  source:
+    type: stdlib
+- name: optparse
+  version: '0'
+  source:
+    type: stdlib
+- name: parallel
+  version: '1.20'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: parser
+  version: '3.2'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: pp
+  version: '0'
+  source:
+    type: stdlib
+- name: prettyprint
+  version: '0'
+  source:
+    type: stdlib
+- name: prism
+  version: 1.9.0
+  source:
+    type: rubygems
+- name: rack
+  version: '2.2'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: rails-dom-testing
+  version: '2.0'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: rails-html-sanitizer
+  version: '1.6'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: railties
+  version: '6.0'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: rainbow
+  version: '3.0'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: rake
+  version: '13.0'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: rbs
+  version: 3.10.3
+  source:
+    type: rubygems
+- name: rbs-inline
+  version: 0.13.0
+  source:
+    type: rubygems
+- name: rbs_rails
+  version: 0.13.0
+  source:
+    type: rubygems
+- name: rdoc
+  version: '0'
+  source:
+    type: stdlib
+- name: regexp_parser
+  version: '2.8'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: rubocop
+  version: '1.57'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: rubocop-ast
+  version: '1.46'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: securerandom
+  version: '0'
+  source:
+    type: stdlib
+- name: simplecov
+  version: '0.22'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: singleton
+  version: '0'
+  source:
+    type: stdlib
+- name: socket
+  version: '0'
+  source:
+    type: stdlib
+- name: sqlite3
+  version: '2.0'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: stringio
+  version: '0'
+  source:
+    type: stdlib
+- name: strscan
+  version: '0'
+  source:
+    type: stdlib
+- name: tempfile
+  version: '0'
+  source:
+    type: stdlib
+- name: thor
+  version: '1.2'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: time
+  version: '0'
+  source:
+    type: stdlib
+- name: timeout
+  version: '0'
+  source:
+    type: stdlib
+- name: tsort
+  version: '0'
+  source:
+    type: stdlib
+- name: tzinfo
+  version: '2.0'
+  source:
+    type: git
+    name: ruby/gem_rbs_collection
+    revision: 1acc2fda1726ddac0bd60c4da369ce7266479413
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    repo_dir: gems
+- name: uri
+  version: '0'
+  source:
+    type: stdlib
+gemfile_lock_path: Gemfile.lock

data/rbs_collection.yaml

@@ -0,0 +1,19 @@
+# Download sources
+sources:
+  - type: git
+    name: ruby/gem_rbs_collection
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    revision: main
+    repo_dir: gems
+
+# You can specify local directories as sources also.
+# - type: local
+#   path: path/to/your/local/repository
+
+# A directory to install the downloaded RBSs
+path: .gem_rbs_collection
+
+# gems:
+#   # If you want to avoid installing rbs files for gems, you can specify them here.
+#   - name: GEM_NAME
+#     ignore: true