exwiw 0.9.8 → 0.9.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2aa2a3c673085993f1f62cd055370eef814301b9298bc486d7f49f71e4470ccc
-  data.tar.gz: 04f5a73f8001d45e402a9d72839bcc824974e9aab4feff998cabc5b4311b762e
+  metadata.gz: 8b734fe407ce3c430c3197b04db275df36640849f6795d7636614d8fab0c6574
+  data.tar.gz: 4be4a94e18f929ef13c97072248e4c7b7e867ad80160841a81c0146a929b9e21
 SHA512:
-  metadata.gz: c6a284caef2d3e5eb78d9252f36ef44a2f7e2d8531274ab13eedda9be0261cc9747319c211b556b17ebba1b471526df6bbea76670fed9005bca302f442582f26
-  data.tar.gz: fd3ec7cdf18b6db28b194a4fe694f09deb79a39428dc280c27709725f0619b24d6f8d361b02192558f20e51ad63b8028f565a3b5e98b9ab8d5dfeb57c51b73ef
+  metadata.gz: cdb946b9f0b3ae2bfca4aa74aca93454cbc0ae6f332f0900216c3a35be9d8bdcef2b2082744bcc6262b6bc9cf72afae9a477c85f7e00d60da8d6eaa4ed55b825
+  data.tar.gz: 12f63468a2d834e558b98e73937e739aa2ab4581cf83699e0a675e280cfd6e6f158d136156400e3ec7c7672beaa63189a6e90c727cc1c87281412e061c72b417

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.9.9] - 2026-07-09
+
+### Changed
+
+- **`replace_with_fake_data` name types now produce a coherent identity, and gained kana types.** The person-family types (`human_name`, `first_name`, `last_name`) previously drew from three independent faker pools, so a single seed's first name, last name, and full name were unrelated people. They now share one per-locale pool of whole people keyed by the seed, so for a given seed `human_name` always equals `last_name` + `first_name` (ordered per locale: `姓 名` for `ja`, `First Last` otherwise). Three kana types are added — `human_name_kana`, `first_name_kana`, `last_name_kana` — for the reading of the same person. Because faker's `ja` locale has kanji names with no readings, exwiw bundles its own paired (kanji, katakana) dataset (`Exwiw::JapaneseNames`) and builds the `ja` name pool from it, so kana matches the kanji and a `ja`-name-only config needs no faker at all. Kana types require `locale: ja` (they raise a clear error otherwise). The person pool is sized independently of the other types at 20,000 (`PERSON_POOL_SIZE`), and for `ja` is filled with 20,000 *distinct* people enumerated from a 142×142 name dataset (rather than sampled with replacement, which left ~37% of slots duplicated), so the name space is large and evenly used. Determinism for the `ja` name family is now pinned to exwiw's bundled dataset version rather than the faker version; other types and locales are unchanged.
+
 ## [0.9.8] - 2026-07-09
 
 ### Added

data/README.md

@@ -850,34 +850,57 @@ fake value, across tables, runs, and adapters:
   because their text forms differ per adapter. A `NULL` seed value hashes `""`
   (still deterministic).
 - Like `replace_with`, it **preserves NULL** in the target column.
-- `locale` (optional) sets the faker locale used to generate the candidate
-  values, e.g. `{ "seed": "id", "type": "human_name", "locale": "ja" }` produces
-  Japanese names.
+- `locale` (optional) sets the locale used to build the candidate values, e.g.
+  `{ "seed": "id", "type": "human_name", "locale": "ja" }` produces Japanese
+  names.
 - Supported `type`s:
 
-  | type | example output |
-  |------|----------------|
-  | `human_name` | `Adrianna Kilback` |
-  | `first_name` | `Adrianna` |
-  | `last_name` | `Kilback` |
-  | `phone_number` | `(555) 123-4567` |
-  | `address` | `282 Kevin Brook, Imogeneborough, CA 58517` |
-  | `company_name` | `Hirthe-Ritchie` |
-  | `email` | `cliff.fay.9d6b804eff5a3f57@example.com` |
-  | `username` | `cliff.fay_9d6b804eff5a3f57` |
-
-- Values are drawn from a pool of 10,000 pre-generated candidates per
-  (type, locale), so distinct seeds can share a fake value. The
+  | type | example output (en) | example output (`locale: ja`) |
+  |------|----------------|----------------|
+  | `human_name` | `Adrianna Kilback` | `山田 太郎` |
+  | `first_name` | `Adrianna` | `太郎` |
+  | `last_name` | `Kilback` | `山田` |
+  | `human_name_kana` | — (ja only) | `ヤマダ タロウ` |
+  | `first_name_kana` | — (ja only) | `タロウ` |
+  | `last_name_kana` | — (ja only) | `ヤマダ` |
+  | `phone_number` | `(555) 123-4567` | |
+  | `address` | `282 Kevin Brook, Imogeneborough, CA 58517` | |
+  | `company_name` | `Hirthe-Ritchie` | |
+  | `email` | `cliff.fay.9d6b804eff5a3f57@example.com` | |
+  | `username` | `cliff.fay_9d6b804eff5a3f57` | |
+
+- **Coherent identity across the name family.** The person-family types
+  (`human_name`, `first_name`, `last_name` and their `*_kana` counterparts) all
+  draw from a single shared pool of people per locale, keyed by the same seed —
+  so for one seed value the last name, first name, full name, and every kana
+  reading belong to the **same person**: `human_name` always equals
+  `last_name` + `first_name`, and `human_name_kana` matches `human_name`. Full
+  names are ordered per locale (`姓 名` for `ja`, `First Last` otherwise).
+- **Kana (`*_kana`) types require `locale: ja`.** faker's `ja` locale ships
+  kanji names with no reading, so exwiw bundles its own paired (kanji, katakana)
+  dataset for `ja`; this is what lets a fake person carry a kana reading that
+  actually matches its kanji. Requesting a `*_kana` type with any other locale
+  raises a clear error at build time.
+- Values are drawn from a pre-generated pool per (type, locale), so distinct
+  seeds can share a fake value. The name family uses one shared **person** pool
+  of 20,000 identities — for `ja` these are 20,000 *distinct* people enumerated
+  from the bundled (kanji, kana) dataset (142 surnames × 142 given names); the
+  other types use an independent 10,000-candidate pool. The
   uniqueness-sensitive types (`email`, `username`) additionally embed a 64-bit
   hex token derived from the seed hash, so they stay collision-free under a
   unique index even at millions of rows (collision probability at 5M distinct
   seeds ≈ 7e-7) and always use the `example.com` domain.
-- **Determinism caveat**: values are stable for a given faker gem version +
-  locale. Upgrading faker (or changing `locale`) regenerates the pool and maps
+- **Determinism caveat**: values are stable for a given locale plus the version
+  of the value source — the faker gem for the non-`ja` name family and the
+  independent types, and exwiw's bundled dataset for the `ja` name family.
+  Upgrading that source (or changing `locale`) regenerates the pool and maps
   seeds to different values. The seed→value mapping itself never changes within
   one version.
 - The faker gem is **not** a runtime dependency of exwiw — add `gem "faker"` to
-  your Gemfile to use this mode (exwiw raises a clear error otherwise).
+  your Gemfile to use this mode (exwiw raises a clear error otherwise). A config
+  that uses **only** `ja` person types needs no faker (that pool is built
+  entirely from the bundled dataset); faker is required for every other type
+  and locale.
 - Exclusive with the other masking keys on the same column. SQL adapters only
   (the MongoDB adapter rejects the key on load, see
   [Unknown keys are rejected](#unknown-keys-are-rejected)), and invisible to

data/lib/exwiw/japanese_names.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+module Exwiw
+  # Paired (kanji, katakana) Japanese name data for the `ja` locale of the
+  # person-family `replace_with_fake_data` types (see {RowTransformer}).
+  #
+  # faker's `ja` locale ships kanji names only, with no reading, so it cannot
+  # produce kana (フリガナ) at all, and its last_name / first_name pools are
+  # unrelated to each other. exwiw bundles this paired dataset instead so that:
+  #
+  # - a fake person carries a kana reading that actually matches its kanji, and
+  # - last_name / first_name / full name (and their kana) for a single seed all
+  #   come from the same person (a coherent identity).
+  #
+  # The kanji sets extend faker's `ja` name list (its top 100 surnames / 100
+  # given names) with common additions; exwiw supplies the readings. 142 x 142
+  # = 20,164 combinations exceeds the person pool size
+  # (RowTransformer::PERSON_POOL_SIZE = 20,000), so the ja pool is filled with
+  # that many DISTINCT people rather than repeating a small subset.
+  #
+  # Readings are katakana (matching the katakana convention of typical `*_kana`
+  # columns). They are plausible common readings, not the only possible reading
+  # of each kanji — fake data only needs to look real, not be canonical.
+  module JapaneseNames
+    SURNAMES = [
+      %w[佐藤 サトウ],
+      %w[鈴木 スズキ],
+      %w[高橋 タカハシ],
+      %w[田中 タナカ],
+      %w[伊藤 イトウ],
+      %w[山本 ヤマモト],
+      %w[渡辺 ワタナベ],
+      %w[中村 ナカムラ],
+      %w[小林 コバヤシ],
+      %w[加藤 カトウ],
+      %w[吉田 ヨシダ],
+      %w[山田 ヤマダ],
+      %w[佐々木 ササキ],
+      %w[山口 ヤマグチ],
+      %w[松本 マツモト],
+      %w[井上 イノウエ],
+      %w[木村 キムラ],
+      %w[林 ハヤシ],
+      %w[斎藤 サイトウ],
+      %w[清水 シミズ],
+      %w[山崎 ヤマザキ],
+      %w[阿部 アベ],
+      %w[森 モリ],
+      %w[池田 イケダ],
+      %w[橋本 ハシモト],
+      %w[山下 ヤマシタ],
+      %w[石川 イシカワ],
+      %w[中島 ナカジマ],
+      %w[前田 マエダ],
+      %w[藤田 フジタ],
+      %w[後藤 ゴトウ],
+      %w[小川 オガワ],
+      %w[岡田 オカダ],
+      %w[村上 ムラカミ],
+      %w[長谷川 ハセガワ],
+      %w[近藤 コンドウ],
+      %w[石井 イシイ],
+      %w[斉藤 サイトウ],
+      %w[坂本 サカモト],
+      %w[遠藤 エンドウ],
+      %w[藤井 フジイ],
+      %w[青木 アオキ],
+      %w[福田 フクダ],
+      %w[三浦 ミウラ],
+      %w[西村 ニシムラ],
+      %w[藤原 フジワラ],
+      %w[太田 オオタ],
+      %w[松田 マツダ],
+      %w[原田 ハラダ],
+      %w[岡本 オカモト],
+      %w[中野 ナカノ],
+      %w[中川 ナカガワ],
+      %w[小野 オノ],
+      %w[田村 タムラ],
+      %w[竹内 タケウチ],
+      %w[金子 カネコ],
+      %w[中山 ナカヤマ],
+      %w[和田 ワダ],
+      %w[石田 イシダ],
+      %w[工藤 クドウ],
+      %w[上田 ウエダ],
+      %w[原 ハラ],
+      %w[森田 モリタ],
+      %w[酒井 サカイ],
+      %w[横山 ヨコヤマ],
+      %w[柴田 シバタ],
+      %w[宮崎 ミヤザキ],
+      %w[宮本 ミヤモト],
+      %w[内田 ウチダ],
+      %w[高木 タカギ],
+      %w[谷口 タニグチ],
+      %w[安藤 アンドウ],
+      %w[丸山 マルヤマ],
+      %w[今井 イマイ],
+      %w[大野 オオノ],
+      %w[高田 タカダ],
+      %w[菅原 スガワラ],
+      %w[河野 コウノ],
+      %w[武田 タケダ],
+      %w[藤本 フジモト],
+      %w[上野 ウエノ],
+      %w[杉山 スギヤマ],
+      %w[千葉 チバ],
+      %w[村田 ムラタ],
+      %w[増田 マスダ],
+      %w[小島 コジマ],
+      %w[小山 コヤマ],
+      %w[大塚 オオツカ],
+      %w[平野 ヒラノ],
+      %w[久保 クボ],
+      %w[渡部 ワタナベ],
+      %w[松井 マツイ],
+      %w[菊地 キクチ],
+      %w[岩崎 イワサキ],
+      %w[松尾 マツオ],
+      %w[佐野 サノ],
+      %w[木下 キノシタ],
+      %w[野口 ノグチ],
+      %w[野村 ノムラ],
+      %w[新井 アライ],
+%w[北村 キタムラ],
+%w[平田 ヒラタ],
+%w[森本 モリモト],
+%w[荒木 アラキ],
+%w[大西 オオニシ],
+%w[菅野 カンノ],
+%w[小池 コイケ],
+%w[桜井 サクライ],
+%w[高野 タカノ],
+%w[川口 カワグチ],
+%w[大久保 オオクボ],
+%w[中田 ナカタ],
+%w[川崎 カワサキ],
+%w[飯田 イイダ],
+%w[星野 ホシノ],
+%w[岩田 イワタ],
+%w[大森 オオモリ],
+%w[松岡 マツオカ],
+%w[沢田 サワダ],
+%w[内藤 ナイトウ],
+%w[松浦 マツウラ],
+%w[西田 ニシダ],
+%w[白石 シライシ],
+%w[浜田 ハマダ],
+%w[早川 ハヤカワ],
+%w[永井 ナガイ],
+%w[松村 マツムラ],
+%w[三宅 ミヤケ],
+%w[福島 フクシマ],
+%w[大橋 オオハシ],
+%w[中西 ナカニシ],
+%w[吉川 ヨシカワ],
+%w[服部 ハットリ],
+%w[尾崎 オザキ],
+%w[水野 ミズノ],
+%w[香川 カガワ],
+%w[荒井 アライ],
+%w[田口 タグチ],
+%w[江口 エグチ],
+%w[秋山 アキヤマ],
+%w[黒田 クロダ],
+%w[今村 イマムラ],
+    ].freeze
+
+    GIVEN_NAMES = [
+      %w[翔太 ショウタ],
+      %w[蓮 レン],
+      %w[翔 ショウ],
+      %w[陸 リク],
+      %w[颯太 ソウタ],
+      %w[悠斗 ユウト],
+      %w[大翔 ヒロト],
+      %w[翼 ツバサ],
+      %w[樹 イツキ],
+      %w[奏太 ソウタ],
+      %w[大和 ヤマト],
+      %w[大輝 ダイキ],
+      %w[悠 ユウ],
+      %w[隼人 ハヤト],
+      %w[健太 ケンタ],
+      %w[大輔 ダイスケ],
+      %w[駿 シュン],
+      %w[陽斗 ハルト],
+      %w[優 ユウ],
+      %w[陽 ヨウ],
+      %w[悠人 ユウト],
+      %w[誠 マコト],
+      %w[拓海 タクミ],
+      %w[仁 ジン],
+      %w[悠太 ユウタ],
+      %w[悠真 ユウマ],
+      %w[大地 ダイチ],
+      %w[健 ケン],
+      %w[遼 リョウ],
+      %w[大樹 ダイキ],
+      %w[諒 リョウ],
+      %w[響 ヒビキ],
+      %w[太一 タイチ],
+      %w[一郎 イチロウ],
+      %w[優斗 ユウト],
+      %w[亮 リョウ],
+      %w[海斗 カイト],
+      %w[颯 ソウ],
+      %w[亮太 リョウタ],
+      %w[匠 タクミ],
+      %w[陽太 ヨウタ],
+      %w[航 ワタル],
+      %w[瑛太 エイタ],
+      %w[直樹 ナオキ],
+      %w[空 ソラ],
+      %w[光 ヒカル],
+      %w[太郎 タロウ],
+      %w[輝 ヒカル],
+      %w[一輝 カズキ],
+      %w[蒼 アオイ],
+      %w[葵 アオイ],
+      %w[優那 ユウナ],
+      %w[優奈 ユウナ],
+      %w[凛 リン],
+      %w[陽菜 ヒナ],
+      %w[愛 アイ],
+      %w[結衣 ユイ],
+      %w[美咲 ミサキ],
+      %w[楓 カエデ],
+      %w[さくら サクラ],
+      %w[遥 ハルカ],
+      %w[美優 ミユ],
+      %w[莉子 リコ],
+      %w[七海 ナナミ],
+      %w[美月 ミヅキ],
+      %w[結菜 ユナ],
+      %w[真央 マオ],
+      %w[花音 カノン],
+      %w[陽子 ヨウコ],
+      %w[舞 マイ],
+      %w[美羽 ミウ],
+      %w[優衣 ユイ],
+      %w[未来 ミク],
+      %w[彩 アヤ],
+      %w[彩乃 アヤノ],
+      %w[彩花 アヤカ],
+      %w[智子 トモコ],
+      %w[奈々 ナナ],
+      %w[千尋 チヒロ],
+      %w[愛美 マナミ],
+      %w[優菜 ユウナ],
+      %w[杏 アン],
+      %w[裕子 ユウコ],
+      %w[芽衣 メイ],
+      %w[綾乃 アヤノ],
+      %w[琴音 コトネ],
+      %w[桜 サクラ],
+      %w[恵 メグミ],
+      %w[杏奈 アンナ],
+      %w[美桜 ミオ],
+      %w[優花 ユウカ],
+      %w[玲奈 レナ],
+      %w[結 ユイ],
+      %w[茜 アカネ],
+      %w[美穂 ミホ],
+      %w[明日香 アスカ],
+      %w[愛子 アイコ],
+      %w[美緒 ミオ],
+      %w[千夏 チナツ],
+      %w[真希 マキ],
+%w[陽向 ヒナタ],
+%w[大介 ダイスケ],
+%w[涼介 リョウスケ],
+%w[悠介 ユウスケ],
+%w[拓也 タクヤ],
+%w[和也 カズヤ],
+%w[直人 ナオト],
+%w[雄太 ユウタ],
+%w[翔平 ショウヘイ],
+%w[健太郎 ケンタロウ],
+%w[慎太郎 シンタロウ],
+%w[竜也 タツヤ],
+%w[圭 ケイ],
+%w[樹里 ジュリ],
+%w[花子 ハナコ],
+%w[由美 ユミ],
+%w[由美子 ユミコ],
+%w[美穂子 ミホコ],
+%w[直子 ナオコ],
+%w[京子 キョウコ],
+%w[順子 ジュンコ],
+%w[洋子 ヨウコ],
+%w[幸子 サチコ],
+%w[美和 ミワ],
+%w[理沙 リサ],
+%w[麻衣 マイ],
+%w[早紀 サキ],
+%w[春香 ハルカ],
+%w[沙織 サオリ],
+%w[香織 カオリ],
+%w[友美 トモミ],
+%w[恵子 ケイコ],
+%w[真由美 マユミ],
+%w[里奈 リナ],
+%w[彩香 アヤカ],
+%w[亜美 アミ],
+%w[春菜 ハルナ],
+%w[千秋 チアキ],
+%w[桃子 モモコ],
+%w[美里 ミサト],
+%w[結子 ユウコ],
+%w[陽介 ヨウスケ],
+    ].freeze
+  end
+end

data/lib/exwiw/row_transformer.rb

@@ -2,6 +2,8 @@
 
 require "digest"
 
+require_relative "japanese_names"
+
 module Exwiw
   # Applies the Ruby-process-side masking modes — `map` and
   # `replace_with_fake_data` — to the rows streamed out of a SQL adapter's
@@ -31,16 +33,46 @@ module Exwiw
     # given faker gem version + locale.
     POOL_RANDOM_SEED = 715_517
 
-    # Supported `replace_with_fake_data` types. `pool` builds one candidate
-    # value (called POOL_SIZE times under a seeded Faker random). Types with
-    # `compose` are uniqueness-sensitive: the pooled base alone would collide
-    # under a unique index at scale, so the final value composes the base with
-    # a 64-bit hex token derived from the same seed digest (collision
-    # probability at 5M distinct seeds ≈ 7e-7).
+    # The person pool (PERSON_TYPES) is sized independently of POOL_SIZE — at
+    # twice the size — so the coherent-identity name space is larger without
+    # disturbing the independent types' seed->value mappings. The ja pool is
+    # filled with distinct people (see .build_japanese_person_pool), so
+    # JapaneseNames must supply at least this many (surname, given) combinations.
+    PERSON_POOL_SIZE = POOL_SIZE * 2
+
+    # A coherent fake identity. All person-family types (PERSON_TYPES) draw
+    # from one shared pool of these per locale, and a seed picks the same pool
+    # index for every such column — so last_name / first_name / full name (and
+    # their kana) for one seed all belong to the same person. kana fields are
+    # only populated for the `ja` locale (faker has no readings; exwiw bundles
+    # a paired dataset — see JapaneseNames); they are nil otherwise.
+    Person = Struct.new(:last_name, :first_name, :last_name_kana, :first_name_kana)
+
+    # Person-family types: they share the per-locale person pool (built by
+    # .person_pool), and each extractor derives its value from the picked
+    # Person. Full-name ordering is locale-aware ("姓 名" for ja, "First Last"
+    # elsewhere). This is what keeps a single seed's name columns consistent.
+    PERSON_TYPES = {
+      "human_name"      => ->(p, locale) { join_full_name(p.last_name, p.first_name, locale) },
+      "last_name"       => ->(p, _locale) { p.last_name },
+      "first_name"      => ->(p, _locale) { p.first_name },
+      "human_name_kana" => ->(p, locale) { join_full_name(p.last_name_kana, p.first_name_kana, locale) },
+      "last_name_kana"  => ->(p, _locale) { p.last_name_kana },
+      "first_name_kana" => ->(p, _locale) { p.first_name_kana },
+    }.freeze
+
+    # Person-family types whose value is a kana reading, only available for the
+    # `ja` locale (the person pool carries nil kana for other locales, so these
+    # are rejected at build time with a clear error).
+    KANA_TYPES = %w[human_name_kana last_name_kana first_name_kana].freeze
+
+    # Independent (non-person) types. `pool` builds one candidate value (called
+    # POOL_SIZE times under a seeded Faker random). Types with `compose` are
+    # uniqueness-sensitive: the pooled base alone would collide under a unique
+    # index at scale, so the final value composes the base with a 64-bit hex
+    # token derived from the same seed digest (collision probability at 5M
+    # distinct seeds ≈ 7e-7).
     FAKE_TYPES = {
-      "human_name"   => { pool: -> { Faker::Name.name } },
-      "first_name"   => { pool: -> { Faker::Name.first_name } },
-      "last_name"    => { pool: -> { Faker::Name.last_name } },
       "phone_number" => { pool: -> { Faker::PhoneNumber.phone_number } },
       "address"      => { pool: -> { Faker::Address.full_address } },
       "company_name" => { pool: -> { Faker::Company.name } },
@@ -50,6 +82,13 @@ module Exwiw
                           compose: ->(base, token) { "#{base}_#{token}" } },
     }.freeze
 
+    # "姓 名" for Japanese, "First Last" otherwise. A nil part (e.g. missing
+    # kana) collapses so the result never has a dangling separator.
+    def self.join_full_name(last, first, locale)
+      parts = locale.to_s == "ja" ? [last, first] : [first, last]
+      parts.compact.join(" ")
+    end
+
     # The `r` a map proc receives: read-only access to the current row's
     # values by column name (`r['id']`). One instance is reused across all
     # rows (zero per-row allocation) — do not retain it outside the proc.
@@ -118,6 +157,15 @@ module Exwiw
             "Add `gem \"faker\"` to your Gemfile (it is not a runtime dependency of exwiw)."
     end
 
+    # Whether a (type, locale) draws any value from faker. The `ja` person pool
+    # is built entirely from exwiw's bundled dataset, so a config that only
+    # uses `ja` person types needs no faker at all.
+    def self.type_needs_faker?(type, locale)
+      return true if FAKE_TYPES.key?(type)
+
+      PERSON_TYPES.key?(type) && locale.to_s != "ja"
+    end
+
     # Pools are memoized per (type, locale): every column sharing a type+locale
     # sees the same pool, which is what makes equal seed values map to equal
     # fake values across tables and runs.
@@ -138,6 +186,51 @@ module Exwiw
       Faker::Config.random = previous_random
     end
 
+    # One pool of coherent Person records per locale, shared by every
+    # person-family type. Memoized so equal seeds map to equal people across
+    # tables and runs. `ja` is built from exwiw's bundled (kanji, kana) dataset
+    # so kana matches kanji; other locales use faker (no kana).
+    def self.person_pool(locale)
+      @person_pools ||= {}
+      @person_pools[locale] ||= build_person_pool(locale)
+    end
+
+    def self.build_person_pool(locale)
+      random = Random.new(POOL_RANDOM_SEED)
+      return build_japanese_person_pool(random) if locale.to_s == "ja"
+
+      previous_locale = Faker::Config.locale
+      previous_random = Faker::Config.random
+      Faker::Config.locale = locale if locale
+      Faker::Config.random = random
+      Array.new(PERSON_POOL_SIZE) { Person.new(Faker::Name.last_name, Faker::Name.first_name, nil, nil).freeze }.freeze
+    ensure
+      unless locale.to_s == "ja"
+        Faker::Config.locale = previous_locale
+        Faker::Config.random = previous_random
+      end
+    end
+
+    # Fill the ja pool with DISTINCT people: enumerate every (surname, given)
+    # combination, shuffle deterministically, and take PERSON_POOL_SIZE. Unlike
+    # sampling with replacement (which wastes ~37% of slots to duplicates), this
+    # gives PERSON_POOL_SIZE distinct identities — so JapaneseNames must supply
+    # at least that many combinations.
+    def self.build_japanese_person_pool(random)
+      surnames = JapaneseNames::SURNAMES
+      given_names = JapaneseNames::GIVEN_NAMES
+      combinations = surnames.size * given_names.size
+      if combinations < PERSON_POOL_SIZE
+        raise "JapaneseNames has #{combinations} (surname, given) combinations, " \
+              "need at least PERSON_POOL_SIZE=#{PERSON_POOL_SIZE}"
+      end
+
+      people = surnames.flat_map do |last|
+        given_names.map { |first| Person.new(last[0], first[0], last[1], first[1]).freeze }
+      end
+      people.shuffle(random: random).first(PERSON_POOL_SIZE).freeze
+    end
+
     def initialize(table)
       @table_name = table.name
       @name_to_index = {}
@@ -145,7 +238,11 @@ module Exwiw
       @name_to_index.freeze
       @row_accessor = Row.new(@table_name, @name_to_index)
 
-      self.class.require_faker! if table.columns.any?(&:replace_with_fake_data)
+      needs_faker = table.columns.any? do |column|
+        fd = column.replace_with_fake_data
+        fd && self.class.type_needs_faker?(fd.type, fd.locale)
+      end
+      self.class.require_faker! if needs_faker
 
       @transforms = table.columns.each_with_index.filter_map do |column, index|
         if column.map
@@ -210,11 +307,26 @@ module Exwiw
 
     private def compile_fake(column, column_index)
       fake_data = column.replace_with_fake_data
-      spec = FAKE_TYPES.fetch(fake_data.type)
+      type = fake_data.type
+      unless PERSON_TYPES.key?(type) || FAKE_TYPES.key?(type)
+        raise ArgumentError,
+              "replace_with_fake_data for column '#{@table_name}.#{column.name}': " \
+              "unknown type '#{type}'. Supported: #{(PERSON_TYPES.keys + FAKE_TYPES.keys).join(', ')}"
+      end
 
-      # Re-resolve the seed here, against the effective (post-ignore) columns:
-      # load-time validation sees the full column list, so a seed column that
-      # was ignore:true is only caught at dump time.
+      seed_index = resolve_seed_index(fake_data, column)
+
+      if PERSON_TYPES.key?(type)
+        compile_person_fake(fake_data, column, column_index, seed_index)
+      else
+        compile_independent_fake(fake_data, column_index, seed_index)
+      end
+    end
+
+    # Re-resolve the seed here, against the effective (post-ignore) columns:
+    # load-time validation sees the full column list, so a seed column that was
+    # ignore:true is only caught at dump time.
+    private def resolve_seed_index(fake_data, column)
       seed_column = fake_data.seed.delete_prefix("#{@table_name}.")
       seed_index = @name_to_index[seed_column]
       unless seed_index
@@ -223,14 +335,44 @@ module Exwiw
               "seed '#{fake_data.seed}' does not resolve to an extracted column " \
               "(is it ignore:true?)"
       end
+      seed_index
+    end
+
+    # Person-family type: pick a coherent Person from the per-locale pool. The
+    # digest[0,8] index is shared with every other person column, so one seed's
+    # name columns all belong to the same person.
+    private def compile_person_fake(fake_data, column, column_index, seed_index)
+      type = fake_data.type
+      locale = fake_data.locale
+      pool = self.class.person_pool(locale)
+      extractor = PERSON_TYPES.fetch(type)
+
+      if KANA_TYPES.include?(type) && pool.first.last_name_kana.nil?
+        raise ArgumentError,
+              "replace_with_fake_data for column '#{@table_name}.#{column.name}': " \
+              "type '#{type}' needs kana readings, which are only available with locale: ja " \
+              "(got locale: #{locale.inspect})"
+      end
+
+      # NULL-preserving like replace_with: a NULL target stays NULL.
+      lambda do |row|
+        next nil if row[column_index].nil?
+
+        digest = Digest::SHA256.digest(row[seed_index].to_s)
+        person = pool[digest[0, 8].unpack1("Q>") % PERSON_POOL_SIZE]
+        extractor.call(person, locale)
+      end
+    end
 
+    # Independent type: pick a value from its own (type, locale) pool.
+    private def compile_independent_fake(fake_data, column_index, seed_index)
       pool = self.class.fake_pool(fake_data.type, fake_data.locale)
-      compose = spec[:compose]
+      compose = FAKE_TYPES.fetch(fake_data.type)[:compose]
 
-      # NULL-preserving like replace_with: a NULL target stays NULL. A nil
-      # seed value hashes "" (deterministic). Seed values are normalized with
-      # to_s so sqlite's native Integer 123 and pg/mysql's string "123" pick
-      # the same fake value.
+      # NULL-preserving like replace_with: a NULL target stays NULL. A nil seed
+      # value hashes "" (deterministic). Seed values are normalized with to_s so
+      # sqlite's native Integer 123 and pg/mysql's string "123" pick the same
+      # fake value.
       lambda do |row|
         next nil if row[column_index].nil?
 

data/lib/exwiw/table_config.rb

@@ -253,10 +253,11 @@ module Exwiw
       fake_data = column.replace_with_fake_data
       return unless fake_data
 
-      unless RowTransformer::FAKE_TYPES.key?(fake_data.type)
+      supported_types = RowTransformer::PERSON_TYPES.keys + RowTransformer::FAKE_TYPES.keys
+      unless supported_types.include?(fake_data.type)
         raise ArgumentError,
               "Table '#{name}' column '#{column.name}': unknown replace_with_fake_data type '#{fake_data.type}' " \
-              "(supported: #{RowTransformer::FAKE_TYPES.keys.join(', ')})."
+              "(supported: #{supported_types.join(', ')})."
       end
 
       seed_column = fake_data.seed.delete_prefix("#{name}.")

data/lib/exwiw/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Exwiw
-  VERSION = "0.9.8"
+  VERSION = "0.9.9"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exwiw
 version: !ruby/object:Gem::Version
-  version: 0.9.8
+  version: 0.9.9
 platform: ruby
 authors:
 - Shia
@@ -71,6 +71,7 @@ files:
 - lib/exwiw/explain_runner.rb
 - lib/exwiw/ext_json.rb
 - lib/exwiw/fake_data.rb
+- lib/exwiw/japanese_names.rb
 - lib/exwiw/mongo_query.rb
 - lib/exwiw/mongodb_collection_config.rb
 - lib/exwiw/mongodb_field.rb