name_bank 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8985bb6db2329f6ae7033a3cd2ca2e9f2f1f4af803bf5904fd4e96d8f0f9034e
-  data.tar.gz: 1fe1d312b363bee756891a16567524d34c845673daa2e2ccb7097d4f1312fc75
+  metadata.gz: fe2659cbdd15df894e97db3be809f9040aa3d58f4c1a3df0353e977053e59dca
+  data.tar.gz: 9172dafa9ee2f5fab0d51eb0a0eb7c7c127241631c06a9306d5899349ccab83b
 SHA512:
-  metadata.gz: 4c55c61b735a271ebac955184ea0e6c7f6207c8be04b87b0ee1e041b5f4f9eb542950204a8756c8f862b4fac94072402333f8357f87c5915c6fd631d06b63457
-  data.tar.gz: 07ca279207e64e4282a6088acd2c379bef69e5df4bc3ec14960e86fd497d765eb07d00402b4d027b4bc9191b8239a43f52fabe71dccb2ba586da8fbce3523a10
+  metadata.gz: fcbc5f7075593a3da579e91cfaadd1503b976f6457d680b55169d66422826e08e1c6ddc1b37b873444e616a94cf393e4e72524f3f93316dc470c858f0654edbc
+  data.tar.gz: 28de093ee1e8e751d6288d659480e240d40755c63a08fa0e59fe4afd23d1ec8e06198634b94bd3f94e9532c086321da90ef9dee10ea2a02a9ba109f2b67b2405

data/CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.6] - 2026-07-24
+
+Tooling and internals only — no API, data or behaviour change.
+
+### Added
+- RuboCop (with rubocop-rspec, rubocop-rake, rubocop-performance) and
+  bundler-audit as development dependencies. The default Rake task now runs
+  `spec`, `rubocop` and `bundle:audit:check`.
+- `rake release_check`: the same checks, but refreshing the advisory database
+  first. Run before releasing.
+
+### Changed
+- Development dependencies moved from the gemspec to the `:development` group
+  in the Gemfile; the gemspec no longer declares any.
+- Internals split for readability: `Repository#names_for_script` extracted from
+  `#pool`, and `SplitScripts.split_country` split into `pools`,
+  `add_native_pools`, `split_file` and `latin_only`.
+- Specs reorganised — class specs under `spec/name_bank/`, one assertion per
+  example.
+
+## [0.1.5] - 2026-07-24
+
+Metadata and documentation only — no API, data or behaviour change.
+
+### Added
+- `spec.metadata` in the gemspec: source, changelog, documentation and bug
+  tracker links, and `rubygems_mfa_required`.
+- README: "Where it fits" (factory_bot, `db/seeds.rb`, RSpec examples) and
+  "Relation to Faker and FFaker" with a comparison table.
+
+### Changed
+- Gem summary and description rewritten so the gem is findable for fake, test
+  and seed name data, and states how it relates to Faker and FFaker.
+- README intro says 106 countries (was "105+").
+
 ## [0.1.4] - 2026-07-24
 
 ### Added

data/README.md

@@ -1,9 +1,13 @@
 # name_bank
 
-Authentic, gender-matched given and family names for 105+ countries. Deep
+Authentic, gender-matched given and family names for 106 countries. Deep
 pools (up to 1500 per country/gender), uniform sampling, deterministic, no
 runtime dependencies.
 
+Realistic fake name data for database seeds, factories, fixtures and demo
+environments — a companion to [Faker](https://github.com/faker-ruby/faker) and
+[FFaker](https://github.com/ffaker/ffaker) for the name part.
+
 ## Installation
 
 Add to your Gemfile:
@@ -42,6 +46,81 @@ Sampling is uniform over each pool and fully deterministic for a given
 `rng` — the same seed always yields the same name. `gender:` is `:male`
 or `:female`.
 
+## Where it fits
+
+A factory_bot factory:
+
+```ruby
+FactoryBot.define do
+  factory :user do
+    transient do
+      country { "DE" }
+      person_gender { :female }
+      rng { Random.new }
+      person { NameBank.full_name(country: country, gender: person_gender, rng: rng) }
+    end
+
+    first_name { person[:firstname] }
+    last_name  { person[:lastname] }
+  end
+end
+```
+
+Database seeds with a fixed seed, so every run produces the same data:
+
+```ruby
+# db/seeds.rb
+rng = Random.new(20_260_724)
+
+%w[DE FR IT ES PL].each do |country|
+  100.times do
+    person = NameBank.full_name(country: country, gender: [:male, :female].sample(random: rng), rng: rng)
+    User.create!(first_name: person[:firstname], last_name: person[:lastname], country: country)
+  end
+end
+```
+
+An RSpec example — the seeded RNG makes the case reproducible:
+
+```ruby
+it "fits a long Cyrillic name into the invoice header" do
+  rng = Random.new(1234)
+  customer = NameBank.full_name(country: "RU", gender: :female, rng: rng, script: :native)
+
+  header = InvoicePdf.new(customer).header
+
+  expect(header).to include(customer[:lastname])
+end
+```
+
+## Relation to Faker and FFaker
+
+Faker and FFaker are full fake-data suites — addresses, companies, lorem ipsum,
+and much more. name_bank does one thing: people names. Use it alongside them,
+not instead of them.
+
+|                      | Faker                                                        | FFaker                                     | name_bank                                                   |
+| -------------------- | ------------------------------------------------------------ | ------------------------------------------ | ----------------------------------------------------------- |
+| Scope                | full fake-data suite                                          | full fake-data suite                        | people names only                                            |
+| Names addressed by   | 58 language/region locales (`de`, `de-AT`, `en-US`)           | 30 language modules (`FFaker::NameDE`)      | 106 ISO country codes (`DE`, `RU`, `JP`)                     |
+| Gendered given names | in about 24 of those locales                                  | in 17 of the 30 name modules                | in every country                                             |
+| Pool depth           | uneven: `en` 1219 m / 4271 f, `de` 574 / 585, `ru` 52 / 56, `ko` 21 | varies per module                     | up to 1500 per country, gender and script; 89 of 106 at the cap |
+| Native script        | one form per locale                                           | one form per module                         | Latin and native as separate pools, 35 countries             |
+| Randomness           | global `Faker::Config.random`                                 | global `FFaker::Random.seed`                | `rng:` passed in per call, no global state                   |
+
+Counts measured against `faker` and `ffaker` `main` on 2026-07-24.
+
+Moving a name call over:
+
+```ruby
+Faker::Name.first_name
+FFaker::NameDE.first_name
+# both: gender-agnostic, locale/module picked from global state
+
+NameBank.first_name(country: "DE", gender: :female, rng: rng)
+# country and gender explicit, RNG explicit
+```
+
 ## Scripts
 
 Names come in Latin (default) and, for countries with a non-Latin writing

data/lib/name_bank/pool_schema.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module NameBank
+  # The pool-key schema: the base YAML keys, how native-script keys are named,
+  # and how a gender maps to its key. Shared by the runtime Repository and the
+  # build-time SplitScripts tool so the key names live in one place.
+  module PoolSchema
+    KEYS = %w[firstnames_male firstnames_female lastnames].freeze
+
+    module_function
+
+    def native_key(key)
+      "#{key}_native"
+    end
+
+    def gender_key(gender)
+      case gender
+      when :male then "firstnames_male"
+      when :female then "firstnames_female"
+      else raise ArgumentError, "gender must be :male or :female, got #{gender.inspect}"
+      end
+    end
+  end
+end

data/lib/name_bank/repository.rb

@@ -5,8 +5,6 @@ require "yaml"
 module NameBank
   # Lazy, memoized loader of per-country name pools stored as YAML in data_dir.
   class Repository
-    KEYS = %w[firstnames_male firstnames_female lastnames].freeze
-
     def initialize(data_dir:)
       @data_dir = data_dir
       @countries_cache = {}
@@ -14,7 +12,7 @@ module NameBank
     end
 
     def firstnames(country:, gender:, variant: nil, script: :latin)
-      pool(load(country, variant), gender_key(gender), script, country)
+      pool(load(country, variant), PoolSchema.gender_key(gender), script, country)
     end
 
     def lastnames(country:, variant: nil, script: :latin)
@@ -23,7 +21,7 @@ module NameBank
 
     def scripts(country:)
       data = load(country, nil)
-      KEYS.any? { |k| data["#{k}_native"]&.any? } ? %i[latin native] : %i[latin]
+      PoolSchema::KEYS.any? { |k| data[PoolSchema.native_key(k)]&.any? } ? %i[latin native] : %i[latin]
     end
 
     def countries
@@ -36,29 +34,24 @@ module NameBank
 
     private
 
-    def gender_key(gender)
-      case gender
-      when :male then "firstnames_male"
-      when :female then "firstnames_female"
-      else raise ArgumentError, "gender must be :male or :female, got #{gender.inspect}"
-      end
-    end
-
     def pool(data, key, script, country)
-      names =
-        case script
-        when :latin then data.fetch(key)
-        when :native
-          native = data["#{key}_native"]
-          native && !native.empty? ? native : data.fetch(key)
-        else
-          raise ArgumentError, "script must be :latin or :native, got #{script.inspect}"
-        end
+      names = names_for_script(data, key, script)
       raise UnknownScript, "#{country}/#{script}" if names.nil? || names.empty?
 
       names
     end
 
+    def names_for_script(data, key, script)
+      case script
+      when :latin then data.fetch(key)
+      when :native
+        native = data[PoolSchema.native_key(key)]
+        native && !native.empty? ? native : data.fetch(key)
+      else
+        raise ArgumentError, "script must be :latin or :native, got #{script.inspect}"
+      end
+    end
+
     def load(country, variant)
       variant ? load_variant(country, variant) : load_country(country)
     end
@@ -85,7 +78,7 @@ module NameBank
       return [] unless Dir.exist?(dir)
 
       Dir.children(dir).select { |f| f.end_with?(".yml") }
-         .map { |f| File.basename(f, ".yml") }.sort
+        .map { |f| File.basename(f, ".yml") }.sort
     end
   end
 end

data/lib/name_bank/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NameBank
-  VERSION = "0.1.4"
+  VERSION = "0.1.6"
 end

data/lib/name_bank.rb

@@ -1,13 +1,17 @@
 # frozen_string_literal: true
 
 require_relative "name_bank/version"
+require_relative "name_bank/pool_schema"
 require_relative "name_bank/repository"
 
+# Authentic, gender-matched given names and surnames for 106 countries,
+# addressed by ISO alpha-2 country code. Sampling is uniform and deterministic
+# from a caller-supplied RNG — no global locale or random state.
 module NameBank
-  Error = Class.new(StandardError)
-  UnknownCountry = Class.new(Error)
-  UnknownVariant = Class.new(Error)
-  UnknownScript = Class.new(Error)
+  class Error < StandardError; end
+  class UnknownCountry < Error; end
+  class UnknownVariant < Error; end
+  class UnknownScript < Error; end
 
   DATA_DIR = File.expand_path("../data", __dir__)
 

metadata

@@ -1,45 +1,24 @@
 --- !ruby/object:Gem::Specification
 name: name_bank
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - Patrick Bartels
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.13'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.13'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-description: A fast, dependency-free generator of authentic, gender-matched given
-  names and surnames for 105+ countries, plus hand-curated pools and cultural variants.
-  Uniform, deterministic sampling from a caller-supplied RNG.
+dependencies: []
+description: 'NameBank generates authentic, gender-matched given names and surnames
+  for 106 countries, addressed by ISO alpha-2 country code, including native-script
+  pools (Cyrillic, Arabic, Han, Hangul, Kana, Greek, Hebrew and more) for 35 of them.
+  Pools hold up to 1500 names per country, gender and script. Use it for realistic
+  fake name data in database seeds, factory_bot factories, RSpec fixtures, demo and
+  staging data. It complements the general-purpose fake data gems Faker and FFaker
+  rather than replacing them: keep those for addresses, companies and lorem ipsum,
+  and use name_bank where you need per-country, gender-matched people names with deep
+  pools. Sampling is uniform and deterministic from a caller-supplied RNG — no global
+  locale or random state. No runtime dependencies.'
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -157,12 +136,18 @@ files:
 - data/variants/US/african_american.yml
 - docs/name-counts.md
 - lib/name_bank.rb
+- lib/name_bank/pool_schema.rb
 - lib/name_bank/repository.rb
 - lib/name_bank/version.rb
 homepage: https://github.com/roughneck/name_bank
 licenses:
 - Apache-2.0
-metadata: {}
+metadata:
+  source_code_uri: https://github.com/roughneck/name_bank
+  changelog_uri: https://github.com/roughneck/name_bank/blob/master/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/name_bank
+  bug_tracker_uri: https://github.com/roughneck/name_bank/issues
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -179,5 +164,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Authentic, gender-matched given and family names for 105+ countries.
+summary: Authentic, gender-matched given names and surnames for 106 countries — fake
+  name data for seeds, factories and tests.
 test_files: []