jp_address_complement 0.1.0

data/sig/generated/generators/jp_address_complement/install_generator.rbs

@@ -0,0 +1,18 @@
+# Generated from lib/generators/jp_address_complement/install_generator.rb with RBS::Inline
+
+module JpAddressComplement
+  module Generators
+    # `rails g jp_address_complement:install` で呼び出されるジェネレーター
+    # 住所テーブル用マイグレーションファイルを利用者アプリの db/migrate/ に生成する
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      # Rails::Generators::Base の RBS に next_migration_number 等が未定義のため steep:ignore
+      # @rbs (String dirname) -> String
+      def self.next_migration_number: (String dirname) -> String
+
+      # @rbs () -> void
+      def create_migration_file: () -> void
+    end
+  end
+end

data/sig/generated/jp_address_complement/configuration.rbs

@@ -0,0 +1,18 @@
+# Generated from lib/jp_address_complement/configuration.rb with RBS::Inline
+
+module JpAddressComplement
+  # Gem の設定を保持するクラス
+  # configure ブロックを通じて repository アダプター・PostalCode の継承元などを注入する
+  class Configuration
+    attr_accessor repository: Repositories::PostalCodeRepository?
+
+    # PostalCode モデルの継承元。nil のときは ActiveRecord::Base。initializer で ApplicationRecord 等に変更可能。
+    attr_accessor postal_code_model_base: Class?
+
+    # PostalCode が参照するテーブル名。nil のときは 'jp_address_complement_postal_codes'。initializer で変更可能。
+    attr_accessor postal_code_table_name: String?
+
+    # @rbs () -> void
+    def initialize: () -> void
+  end
+end

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

@@ -0,0 +1,78 @@
+# Generated from lib/jp_address_complement/importers/csv_importer.rb with RBS::Inline
+
+module JpAddressComplement
+  module Importers
+    # インポート結果（件数報告用）
+    # @rbs type upserted = Integer
+    # @rbs type deleted = Integer
+    class ImportResult < Data
+      attr_reader upserted(): untyped
+
+      attr_reader deleted(): untyped
+
+      def self.new: (untyped upserted, untyped deleted) -> instance
+                  | (upserted: untyped, deleted: untyped) -> instance
+
+      def self.members: () -> [ :upserted, :deleted ]
+
+      def members: () -> [ :upserted, :deleted ]
+    end
+
+    # 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
+
+      COL_PREF: Integer
+
+      COL_CITY: Integer
+
+      COL_TOWN: Integer
+
+      COL_IS_PARTIAL: Integer
+
+      COL_HAS_ALIAS: Integer
+
+      COL_IS_LARGE_OFFICE: Integer
+
+      # @rbs (String csv_path) -> void
+      def initialize: (String csv_path) -> void
+
+      # CSV を読み込み、upsert 後に古いバージョンの行を一括削除する。戻り値は ImportResult。
+      # バージョンは既存レコードの最大値+1 で、別テーブルでは管理しない。
+      # @rbs () -> ImportResult
+      # @return [ImportResult] upserted 件数と deleted 件数
+      def import: () -> ImportResult
+
+      private
+
+      # @rbs (Array[String?] row) -> (Hash[Symbol, untyped] | nil)
+      def parse_row: (Array[String?] row) -> (Hash[Symbol, untyped] | nil)
+
+      # @rbs (Integer import_version) -> [Integer, Hash[untyped, bool]]
+      def read_and_upsert: (Integer import_version) -> [ Integer, Hash[untyped, bool] ]
+
+      # @rbs (Array[Hash[Symbol, untyped]] batch) -> void
+      def upsert_batch: (Array[Hash[Symbol, untyped]] batch) -> void
+
+      # 郵便番号・都道府県・市区町村・町域（漢字）が同じでも読み（カナ）が異なれば別レコードとして扱う
+      # @rbs (Hash[Symbol, untyped] record) -> Array[String]
+      def row_key: (Hash[Symbol, untyped] record) -> Array[String]
+
+      # 今回のインポートより古いバージョンの行を一括削除し、削除件数を返す
+      # @rbs (Integer import_version) -> Integer
+      def delete_obsolete: (Integer import_version) -> Integer
+    end
+  end
+end

data/sig/generated/jp_address_complement/ken_all_downloader.rbs

@@ -0,0 +1,49 @@
+# Generated from lib/jp_address_complement/ken_all_downloader.rb with RBS::Inline
+
+module JpAddressComplement
+  # 郵便番号データ（utf_ken_all.zip）を公式URLからダウンロードし、展開して CSV のパスを返す
+  class KenAllDownloader
+    # @rbs String
+    DEFAULT_URL: ::String
+
+    # @rbs String
+    CSV_FILENAME: ::String
+
+    class DownloadError < JpAddressComplement::Error
+    end
+
+    # @rbs (?String url) -> void
+    # @param url [String] ダウンロードする zip の URL（省略時は DEFAULT_URL）
+    def initialize: (?String url) -> void
+
+    # zip をダウンロードして一時ディレクトリに展開し、KEN_ALL.CSV の絶対パスを返す。
+    # 呼び出し元でインポート完了まで一時ディレクトリは削除されない（プロセス終了時に OS が削除）。
+    # @rbs () -> String
+    # @return [String] 展開された KEN_ALL.CSV の絶対パス
+    # @raise [DownloadError] ダウンロード・展開・ファイルが見つからない場合
+    def download_and_extract: () -> String
+
+    private
+
+    # @rbs () -> String
+    def download_zip: () -> String
+
+    # @rbs (String path) -> void
+    def fetch_to_path: (String path) -> void
+
+    # @rbs (Net::HTTPResponse response, String path) -> void
+    def write_response_to_path: (Net::HTTPResponse response, String path) -> void
+
+    # @rbs (String zip_path) -> String
+    def extract_zip: (String zip_path) -> String
+
+    # @rbs (String zip_path, String tmpdir) -> String?
+    def extract_zip_entries: (String zip_path, String tmpdir) -> String?
+
+    # @rbs (String entry_name, String dest) -> bool
+    def entry_csv?: (String entry_name, String dest) -> bool
+
+    # @rbs (String tmpdir) -> String?
+    def find_csv_in_dir: (String tmpdir) -> String?
+  end
+end

data/sig/generated/jp_address_complement/normalizer.rbs

@@ -0,0 +1,37 @@
+# Generated from lib/jp_address_complement/normalizer.rb with RBS::Inline
+
+module JpAddressComplement
+  # 郵便番号の正規化処理を担当するクラス
+  # 全角→半角変換・〒記号除去・ハイフン除去を行う
+  class Normalizer
+    # 半角数字以外の文字を除去するためのパターン
+    DIGIT_ONLY: Regexp
+
+    PREFIX_MIN_LENGTH: Integer
+
+    # 町域から除去する「通常住所に含まれない」固定文字列（漢字・かな両方）
+    TOWN_DISPLAY_REMOVAL_STRINGS: untyped
+
+    # 郵便番号文字列を正規化して7桁の半角数字文字列を返す
+    # @rbs (String?) -> String?
+    # @param code [String, nil] 郵便番号文字列（ハイフン・全角・〒記号を自動除去）
+    # @return [String, nil] 正規化後の7桁郵便番号。不正な場合は nil
+    def self.normalize_postal_code: (String?) -> String?
+
+    # 郵便番号プレフィックスを正規化する
+    # @rbs (String?) -> String?
+    # @param prefix [String, nil] 郵便番号の先頭部分（4桁以上）
+    # @return [String, nil] 正規化後の数字文字列。4桁未満または不正な場合は nil
+    def self.normalize_prefix: (String?) -> String?
+
+    # 町域文字列から「通常住所に含まれない情報」を除いた表示用文字列を返す
+    # 除去対象: 「以下に掲載がない場合」、全角括弧（）で囲まれた部分全体
+    # @rbs (String?) -> String?
+    # @param town_str [String, nil] 町域（漢字）または町域カナ
+    # @return [String, nil] 除去後の文字列。nil または空になった場合は nil
+    def self.normalize_town_for_display: (String?) -> String?
+
+    # @rbs (String) -> String
+    private def self.normalize_string: (String) -> String
+  end
+end

data/sig/generated/jp_address_complement/prefecture.rbs

@@ -0,0 +1,27 @@
+# Generated from lib/jp_address_complement/prefecture.rb with RBS::Inline
+
+module JpAddressComplement
+  # JIS X 0401 都道府県コード（01–47）⇔都道府県名の変換
+  module Prefecture
+    # JIS X 0401 都道府県コード → 都道府県名（正式名称）
+    CODE_TO_NAME: untyped
+
+    NAME_TO_CODE: untyped
+
+    # 都道府県コードから都道府県名を返す
+    # @rbs (String | Integer | nil) -> String?
+    # @param code [String, Integer, nil] 都道府県コード（01–47）。数値またはゼロパディング文字列
+    # @return [String, nil] 都道府県名。該当なし・不正入力時は nil
+    def self.name_from_code: (String | Integer | nil) -> String?
+
+    # 都道府県名（正式名称）から都道府県コードを2桁文字列で返す
+    # @rbs (String?) -> String?
+    # @param name [String, nil] 都道府県の正式名称
+    # @return [String, nil] 2桁のコード（例: "13"）。該当なし時は nil
+    def self.code_from_name: (String?) -> String?
+
+    def self.normalize_code: (untyped code) -> untyped
+
+    def self.normalize_code_string: (untyped stripped) -> untyped
+  end
+end

data/sig/generated/jp_address_complement/railtie.rbs

@@ -0,0 +1,8 @@
+# Generated from lib/jp_address_complement/railtie.rb with RBS::Inline
+
+module JpAddressComplement
+  # Rails との統合を担う Railtie
+  # @rbs inherits Rails::Railtie
+  class Railtie < Rails::Railtie
+  end
+end

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

@@ -0,0 +1,38 @@
+# Generated from lib/jp_address_complement/repositories/active_record_postal_code_repository.rb with RBS::Inline
+
+module JpAddressComplement
+  module Repositories
+    # ActiveRecord を使用した PostalCodeRepository の実装
+    # Rails 環境向けにバンドルされる標準実装
+    class ActiveRecordPostalCodeRepository < PostalCodeRepository
+      # @rbs (String code) -> Array[AddressRecord]
+      # @param code [String] 正規化済み7桁郵便番号
+      # @return [Array<AddressRecord>]
+      def find_by_code: (String code) -> Array[AddressRecord]
+
+      # @rbs (String prefix) -> Array[AddressRecord]
+      # @param prefix [String] 4桁以上の郵便番号プレフィックス
+      # @return [Array<AddressRecord>]
+      def find_by_prefix: (String prefix) -> Array[AddressRecord]
+
+      # @rbs (pref: String?, city: String?, ?town: String?) -> Array[AddressRecord]
+      def find_postal_codes_by_address: (pref: String?, city: String?, ?town: String?) -> Array[AddressRecord]
+
+      private
+
+      # @rbs (pref: String?, city: String?, ?town: String?) -> untyped
+      def address_relation: (pref: String?, city: String?, ?town: String?) -> untyped
+
+      # @rbs () -> singleton(PostalCode)
+      def postal_code_model: () -> singleton(PostalCode)
+
+      # LIKE 句用に % _ \ をエスケープする
+      # @rbs (String) -> String
+      def escape_like: (String) -> String
+
+      # ActiveRecord の動的属性のため Steep の型が不足する。理由明記で抑制（research §7）
+      # @rbs (untyped postal_code_ar) -> AddressRecord
+      def to_record: (untyped postal_code_ar) -> AddressRecord
+    end
+  end
+end

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

@@ -0,0 +1,100 @@
+# Generated from lib/jp_address_complement/repositories/csv_postal_code_repository.rb with RBS::Inline
+
+module JpAddressComplement
+  module Repositories
+    # UTF-8 版 KEN_ALL（utf_ken_all.csv）形式の CSV ファイルを直接読み込んで検索を行う Repository 実装
+    #
+    # - ActiveRecord や DB に依存せず、純粋に CSV から AddressRecord を構築する
+    # - 初回アクセス時に CSV 全体を読み込み、インメモリでインデックスを構築する（2回目以降はメモリ検索のみ）
+    # - CSV は日本郵便公式の KEN_ALL.CSV（UTF-8 版 utf_ken_all.csv）と同じ列構成を前提とする
+    #
+    # 典型的な利用例:
+    #
+    #   require 'jp_address_complement/repositories/csv_postal_code_repository'
+    #
+    #   JpAddressComplement.configure do |c|
+    #     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
+
+      # @rbs (String csv_path) -> void
+      # @param csv_path [String] 読み込む KEN_ALL 形式 UTF-8 CSV のパス
+      def initialize: (String csv_path) -> void
+
+      # @rbs (String code) -> Array[AddressRecord]
+      def find_by_code: (String code) -> Array[AddressRecord]
+
+      # @rbs (String prefix) -> Array[AddressRecord]
+      def find_by_prefix: (String prefix) -> Array[AddressRecord]
+
+      # @rbs (pref: String?, city: String?, ?town: String?) -> Array[AddressRecord]
+      def find_postal_codes_by_address: (pref: String?, city: String?, ?town: String?) -> Array[AddressRecord]
+
+      private
+
+      # @rbs () -> void
+      def ensure_loaded: () -> void
+
+      # @rbs () -> void
+      def load_csv: () -> void
+
+      # @rbs () -> void
+      def validate_csv_path!: () -> void
+
+      # @rbs () { (Array[String?]) -> void } -> void
+      def each_csv_row: () { (Array[String?]) -> void } -> void
+
+      # @rbs (Array[String?] row) -> void
+      def append_record: (Array[String?] row) -> void
+
+      # @rbs (AddressRecord record, String pref, String city, String? town_query) -> bool
+      def address_match?: (AddressRecord record, String pref, String city, String? town_query) -> bool
+
+      # @rbs (Array[String?] row) -> (AddressRecord | nil)
+      def build_record_from_row: (Array[String?] row) -> (AddressRecord | nil)
+
+      # @rbs (Array[String?] row) -> (Hash[Symbol, untyped] | nil)
+      def parse_row_attrs: (Array[String?] row) -> (Hash[Symbol, untyped] | nil)
+
+      # @rbs (Array[String?] row) -> (Array[String] | nil)
+      def extract_required_fields: (Array[String?] row) -> (Array[String] | nil)
+
+      # @rbs (String? cell) -> (String | nil)
+      def strip_cell: (String? cell) -> (String | nil)
+
+      # @rbs (String? postal_code) -> bool
+      def valid_postal_code_format?: (String? postal_code) -> bool
+
+      # @rbs (Array[String?], String, String, String, String) -> Hash[Symbol, untyped]
+      def build_row_attrs: (Array[String?], String, String, String, String) -> Hash[Symbol, untyped]
+
+      # @rbs (String? cell) -> bool
+      def flag?: (String? cell) -> bool
+
+      # @rbs (untyped value) -> bool
+      def blank?: (untyped value) -> bool
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# Generated from lib/jp_address_complement/repositories/postal_code_repository.rb with RBS::Inline
+
+module JpAddressComplement
+  module Repositories
+    # データアクセスを抽象化するインターフェース基底クラス
+    # 具体的な実装は ActiveRecordPostalCodeRepository またはユーザー定義アダプターで行う
+    class PostalCodeRepository
+      # 7桁郵便番号で完全一致検索する
+      # @rbs (String code) -> Array[AddressRecord]
+      # @param code [String] 正規化済み7桁郵便番号
+      # @return [Array<AddressRecord>]
+      def find_by_code: (String code) -> Array[AddressRecord]
+
+      # 郵便番号プレフィックスで前方一致検索する
+      # @rbs (String prefix) -> Array[AddressRecord]
+      # @param prefix [String] 4桁以上の郵便番号プレフィックス
+      # @return [Array<AddressRecord>]
+      def find_by_prefix: (String prefix) -> Array[AddressRecord]
+
+      # 都道府県・市区町村・町域で検索する（逆引き）。町域は前方一致。
+      # @rbs (pref: String?, city: String?, ?town: String?) -> Array[AddressRecord]
+      # @param pref [String] 都道府県名（正式名称）
+      # @param city [String] 市区町村名
+      # @param town [String, nil] 町域名。省略時は都道府県＋市区町村のみ。指定時は前方一致で候補を返す
+      # @return [Array<AddressRecord>] 該当レコードの配列。該当なし・入力不十分時は []
+      def find_postal_codes_by_address: (pref: String?, city: String?, ?town: String?) -> Array[AddressRecord]
+    end
+  end
+end

data/sig/generated/jp_address_complement/searcher.rbs

@@ -0,0 +1,43 @@
+# Generated from lib/jp_address_complement/searcher.rb with RBS::Inline
+
+module JpAddressComplement
+  # コア検索ロジック
+  # Repository を注入して使用することで ActiveRecord への直接依存を排除する
+  class Searcher
+    # @rbs (Repositories::PostalCodeRepository repository) -> void
+    def initialize: (Repositories::PostalCodeRepository repository) -> void
+
+    # 7桁郵便番号から住所レコードを検索する
+    # @rbs (String? code) -> Array[AddressRecord]
+    # @param code [String, nil] 郵便番号
+    # @return [Array<AddressRecord>]
+    def search_by_postal_code: (String? code) -> Array[AddressRecord]
+
+    # 郵便番号プレフィックスから住所候補を検索する（4桁以上）
+    # @rbs (String? prefix) -> Array[AddressRecord]
+    # @param prefix [String, nil] 郵便番号の先頭部分
+    # @return [Array<AddressRecord>]
+    def search_by_postal_code_prefix: (String? prefix) -> Array[AddressRecord]
+
+    # 郵便番号と住所文字列の整合性を検証する
+    # 日本郵便の 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?: (String? postal_code, String? address) -> bool
+
+    # 都道府県・市区町村・町域から郵便番号候補を取得する（逆引き）。町域は前方一致。
+    # @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: String?, city: String?, ?town: String?) -> Array[[ String, AddressRecord ]]
+
+    private
+
+    def address_matches_record?: (untyped address, untyped record) -> untyped
+  end
+end

data/sig/generated/jp_address_complement/validators/address_validator.rbs

@@ -0,0 +1,24 @@
+# Generated from lib/jp_address_complement/validators/address_validator.rb with RBS::Inline
+
+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: (untyped record) -> void
+
+    private
+
+    def postal_code_field: () -> untyped
+
+    def address_field: () -> untyped
+  end
+end

data/sig/generated/jp_address_complement/version.rbs

@@ -0,0 +1,5 @@
+# Generated from lib/jp_address_complement/version.rb with RBS::Inline
+
+module JpAddressComplement
+  VERSION: String
+end

data/sig/generated/jp_address_complement.rbs

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

data/sig/manual/address_record.rbs

@@ -0,0 +1,40 @@
+# sig/manual/address_record.rbs — AddressRecord (Data.define) の手動型定義
+# contracts/rbs-public-api.md, data-model.md に準拠。rbs-inline では上書きしない。
+
+module JpAddressComplement
+  ADDRESS_RECORD_ATTRIBUTES: Array[Symbol]
+
+  class AddressRecord
+    attr_reader postal_code: String
+    attr_reader pref_code: String
+    attr_reader pref: String
+    attr_reader city: String
+    attr_reader town: String?
+    attr_reader kana_pref: String?
+    attr_reader kana_city: String?
+    attr_reader kana_town: String?
+    attr_reader has_alias: bool
+    attr_reader is_partial: bool
+    attr_reader is_large_office: bool
+
+    def initialize: (
+      postal_code: String,
+      pref_code: String,
+      pref: String,
+      city: String,
+      ?town: String?,
+      ?kana_pref: String?,
+      ?kana_city: String?,
+      ?kana_town: String?,
+      ?has_alias: bool,
+      ?is_partial: bool,
+      ?is_large_office: bool
+    ) -> void
+
+    # 通常住所に含まれない情報を除いた町域名（丁目・番地・その他等の括弧、「以下に掲載がない場合」を除去）
+    def normalized_town: () -> String?
+
+    # 通常住所に含まれない情報を除いた町域カナ
+    def normalized_kana_town: () -> String?
+  end
+end

data/sig/manual/gem_rubyzip.rbs

@@ -0,0 +1,17 @@
+# rubyzip の Steep 用スタブ（Zip::File 等）
+module Zip
+  class Error < StandardError
+  end
+
+  class File
+    def self.open: (String path) { (Zip::File) -> untyped } -> untyped
+
+    def each: () { (Zip::Entry) -> void } -> void
+  end
+
+  class Entry
+    attr_reader name: String
+
+    def extract: (String dest) { (bool) -> void } -> void
+  end
+end

data/sig/manual/postal_code.rbs

@@ -0,0 +1,9 @@
+# sig/manual/postal_code.rbs — PostalCode の手動型定義
+# 継承元は JpAddressComplement.base_record_class（= configuration.postal_code_model_base、未設定時は ActiveRecord::Base）。型上は ActiveRecord::Base の子として扱う。
+
+module JpAddressComplement
+  class PostalCode < ActiveRecord::Base
+    def self.where: (*untyped) -> untyped
+    def self.maximum: (Symbol column) -> Integer?
+  end
+end

data/sig/manual/stdlib_csv_invalid_encoding_error.rbs

@@ -0,0 +1,5 @@
+class CSV
+  class InvalidEncodingError < StandardError
+  end
+end
+