column_anonymizer 0.1.0 → 0.2.0

data/CUSTOM_GENERATORS_GUIDE.md

@@ -1,515 +0,0 @@
-# Custom Anonymization Generators
-
-## Overview
-
-Column Anonymizer allows you to define **custom anonymization types** from within your Rails application. This is perfect for:
-
-- Domain-specific data formats (employee IDs, account numbers, etc.)
-- Company-specific data patterns
-- Specialized anonymization requirements
-- Custom business logic
-
-## Quick Start
-
-### 1. Generate the Initializer
-
-```bash
-rails generate column_anonymizer:initializer
-```
-
-This creates `config/initializers/column_anonymizer.rb` with example generators.
-
-### 2. Register Your Custom Generator
-
-```ruby
-# config/initializers/column_anonymizer.rb
-
-ColumnAnonymizer::Anonymizer.register(:credit_card) do
-  "XXXX-XXXX-XXXX-#{rand(1000..9999)}"
-end
-```
-
-### 3. Use in Your YAML Config
-
-```yaml
-# config/encrypted_columns.yml
-User:
-  credit_card_number: credit_card  # ← Uses your custom generator
-```
-
-### 4. Anonymize!
-
-```ruby
-user = User.first
-ColumnAnonymizer::Anonymizer.anonymize_model!(user)
-
-# credit_card_number becomes: "XXXX-XXXX-XXXX-1234"
-```
-
----
-
-## Registration Methods
-
-### Block Syntax (Recommended)
-
-```ruby
-ColumnAnonymizer::Anonymizer.register(:custom_type) do
-  # Return the anonymized value
-  "ANONYMIZED-#{SecureRandom.hex(4)}"
-end
-```
-
-### Lambda Syntax
-
-```ruby
-ColumnAnonymizer::Anonymizer.register(:uuid, -> { SecureRandom.uuid })
-```
-
-### Callable Object
-
-```ruby
-class EmployeeIdGenerator
-  def self.call
-    "EMP-#{Time.now.year}-#{rand(10000..99999)}"
-  end
-end
-
-ColumnAnonymizer::Anonymizer.register(:employee_id, EmployeeIdGenerator)
-```
-
----
-
-## Example Custom Generators
-
-### Simple Masked Format
-
-```ruby
-ColumnAnonymizer::Anonymizer.register(:credit_card) do
-  "XXXX-XXXX-XXXX-#{rand(1000..9999)}"
-end
-```
-
-### Using Faker
-
-```ruby
-ColumnAnonymizer::Anonymizer.register(:company_name) do
-  Faker::Company.name
-end
-
-ColumnAnonymizer::Anonymizer.register(:job_title) do
-  Faker::Job.title
-end
-```
-
-### Custom Business Logic
-
-```ruby
-ColumnAnonymizer::Anonymizer.register(:account_number) do
-  prefix = "ACC"
-  year = Time.now.year
-  sequence = rand(10000..99999)
-  "#{prefix}#{year}#{sequence}"
-end
-```
-
-### Format-Specific Patterns
-
-```ruby
-ColumnAnonymizer::Anonymizer.register(:license_plate) do
-  letters = ('A'..'Z').to_a.sample(3).join
-  numbers = rand(100..999)
-  "#{letters}-#{numbers}"
-end
-
-ColumnAnonymizer::Anonymizer.register(:vin) do
-  chars = ('A'..'Z').to_a + (0..9).to_a
-  17.times.map { chars.sample }.join
-end
-```
-
-### Using Rails Models/Data
-
-```ruby
-ColumnAnonymizer::Anonymizer.register(:department_name) do
-  Department.active.pluck(:name).sample || "General"
-end
-
-ColumnAnonymizer::Anonymizer.register(:valid_country_code) do
-  Country.all.pluck(:code).sample || "US"
-end
-```
-
-### Date/Time Generators
-
-```ruby
-ColumnAnonymizer::Anonymizer.register(:birth_year) do
-  rand(1950..2005).to_s
-end
-
-ColumnAnonymizer::Anonymizer.register(:recent_timestamp) do
-  (Time.now - rand(1..365).days).iso8601
-end
-```
-
-### Complex Multi-Field Logic
-
-```ruby
-ColumnAnonymizer::Anonymizer.register(:medical_record_number) do
-  hospital_code = "HSP#{rand(100..999)}"
-  year = Time.now.year.to_s[2..3]
-  patient_seq = rand(100000..999999)
-  "#{hospital_code}-#{year}-#{patient_seq}"
-end
-```
-
-### Deterministic (Repeatable) Anonymization
-
-```ruby
-ColumnAnonymizer::Anonymizer.register(:deterministic_id) do
-  # Same input always produces same output
-  Digest::SHA256.hexdigest("#{Time.now.to_date}-#{rand}")[0..15]
-end
-```
-
----
-
-## API Reference
-
-### `register(type, generator = nil, &block)`
-
-Register a custom anonymization generator.
-
-**Parameters:**
-- `type` (Symbol/String) - The identifier to use in YAML config
-- `generator` (Proc/#call) - Optional callable object
-- `&block` - Block that returns anonymized value
-
-**Examples:**
-
-```ruby
-# With block
-ColumnAnonymizer::Anonymizer.register(:custom) do
-  "CUSTOM-#{SecureRandom.hex(4)}"
-end
-
-# With lambda
-ColumnAnonymizer::Anonymizer.register(:uuid, -> { SecureRandom.uuid })
-
-# With callable class
-ColumnAnonymizer::Anonymizer.register(:employee_id, EmployeeIdGenerator)
-```
-
-### `unregister(type)`
-
-Remove a custom generator.
-
-```ruby
-ColumnAnonymizer::Anonymizer.unregister(:credit_card)
-```
-
-### `all_generators`
-
-Get all available generators (built-in + custom).
-
-```ruby
-generators = ColumnAnonymizer::Anonymizer.all_generators
-# => { email: #<Proc>, phone: #<Proc>, credit_card: #<Proc>, ... }
-```
-
-### `generator_exists?(type)`
-
-Check if a generator is registered.
-
-```ruby
-ColumnAnonymizer::Anonymizer.generator_exists?(:credit_card)
-# => true
-```
-
-### `reset_custom_generators!`
-
-Clear all custom generators (useful for testing).
-
-```ruby
-ColumnAnonymizer::Anonymizer.reset_custom_generators!
-```
-
----
-
-## Built-in Generators
-
-No need to register these - they're available by default:
-
-| Type | Example Output | Description |
-|------|----------------|-------------|
-| `:email` | `user_a1b2@example.com` | Fake email addresses |
-| `:phone` | `+15551234567` | Fake phone numbers |
-| `:ssn` | `123-45-6789` | Fake Social Security Numbers |
-| `:name` | `John Doe` | Fake full names |
-| `:first_name` | `John` | Fake first names |
-| `:last_name` | `Smith` | Fake last names |
-| `:address` | `1234 Main St` | Fake addresses |
-| `:text` | `Lorem ipsum...` | Lorem ipsum text |
-
----
-
-## Complete Workflow Example
-
-### Step 1: Create Initializer
-
-```bash
-rails generate column_anonymizer:initializer
-```
-
-### Step 2: Register Custom Generators
-
-```ruby
-# config/initializers/column_anonymizer.rb
-
-# Credit card masking
-ColumnAnonymizer::Anonymizer.register(:credit_card) do
-  "XXXX-XXXX-XXXX-#{rand(1000..9999)}"
-end
-
-# Employee ID
-ColumnAnonymizer::Anonymizer.register(:employee_id) do
-  "EMP-#{Time.now.year}-#{rand(10000..99999)}"
-end
-
-# Medical record number
-ColumnAnonymizer::Anonymizer.register(:mrn) do
-  "MRN#{rand(100000..999999)}"
-end
-```
-
-### Step 3: Update YAML Config
-
-```yaml
-# config/encrypted_columns.yml
-User:
-  email: email                    # Built-in
-  phone: phone                    # Built-in
-  credit_card_number: credit_card # Custom!
-
-Employee:
-  employee_number: employee_id    # Custom!
-  ssn: ssn                        # Built-in
-
-Patient:
-  medical_record_number: mrn      # Custom!
-```
-
-### Step 4: Use Models with Encryption
-
-```ruby
-class User < ApplicationRecord
-  encrypts :email
-  encrypts :phone
-  encrypts :credit_card_number
-end
-
-class Employee < ApplicationRecord
-  encrypts :employee_number
-  encrypts :ssn
-end
-
-class Patient < ApplicationRecord
-  encrypts :medical_record_number
-end
-```
-
-### Step 5: Anonymize Data
-
-```ruby
-# Single record
-user = User.first
-ColumnAnonymizer::Anonymizer.anonymize_model!(user)
-
-# Batch anonymization
-User.find_each do |user|
-  ColumnAnonymizer::Anonymizer.anonymize_model!(user)
-end
-
-# Before:
-# user.credit_card_number => "4532-1234-5678-9012"
-# user.email => "john@example.com"
-
-# After:
-# user.credit_card_number => "XXXX-XXXX-XXXX-7823"
-# user.email => "user_abc123@example.com"
-```
-
----
-
-## Advanced Patterns
-
-### Context-Aware Generators
-
-```ruby
-# Generator that uses model instance context
-# Note: Generators receive no arguments, so you'd need to
-# handle context via other means (e.g., thread-local variables)
-
-ColumnAnonymizer::Anonymizer.register(:age_appropriate_name) do
-  # Generate age-appropriate names
-  birth_year = Thread.current[:anonymizing_birth_year]
-  if birth_year && birth_year > 2000
-    Faker::Name.first_name # Modern name
-  else
-    Faker::Name.middle_name # Classic name
-  end
-end
-```
-
-### Locale-Specific Generators
-
-```ruby
-ColumnAnonymizer::Anonymizer.register(:localized_address) do
-  Faker::Config.locale = :en
-  Faker::Address.full_address
-end
-
-ColumnAnonymizer::Anonymizer.register(:japanese_name) do
-  Faker::Config.locale = :ja
-  Faker::Name.name
-end
-```
-
-### Stateful Generators (Use with Caution)
-
-```ruby
-# Counter-based generator
-counter = 0
-ColumnAnonymizer::Anonymizer.register(:sequential_id) do
-  counter += 1
-  "USER-#{counter.to_s.rjust(6, '0')}"
-end
-```
-
----
-
-## Testing Your Custom Generators
-
-```ruby
-# spec/initializers/column_anonymizer_spec.rb
-
-RSpec.describe "Custom Anonymizers" do
-  before do
-    # Reset to clean state
-    ColumnAnonymizer::Anonymizer.reset_custom_generators!
-  end
-
-  describe "credit_card generator" do
-    before do
-      ColumnAnonymizer::Anonymizer.register(:credit_card) do
-        "XXXX-XXXX-XXXX-#{rand(1000..9999)}"
-      end
-    end
-
-    it "generates masked credit card format" do
-      generator = ColumnAnonymizer::Anonymizer.all_generators[:credit_card]
-      result = generator.call
-      
-      expect(result).to match(/^XXXX-XXXX-XXXX-\d{4}$/)
-    end
-
-    it "is registered and exists" do
-      expect(ColumnAnonymizer::Anonymizer.generator_exists?(:credit_card)).to be true
-    end
-  end
-
-  describe "employee_id generator" do
-    before do
-      ColumnAnonymizer::Anonymizer.register(:employee_id) do
-        "EMP-#{Time.now.year}-#{rand(10000..99999)}"
-      end
-    end
-
-    it "generates employee ID format" do
-      generator = ColumnAnonymizer::Anonymizer.all_generators[:employee_id]
-      result = generator.call
-      
-      expect(result).to match(/^EMP-\d{4}-\d{5}$/)
-    end
-  end
-end
-```
-
----
-
-## Best Practices
-
-### ✅ Do's
-
-- **Keep generators simple** - Single responsibility
-- **Make them fast** - Called potentially thousands of times
-- **Test your generators** - Ensure they produce valid data
-- **Use meaningful type names** - `credit_card` not `cc`
-- **Document your generators** - Add comments explaining the format
-- **Use built-ins when possible** - Don't reinvent the wheel
-
-### ❌ Don'ts
-
-- **Don't make database calls in every generator** - Cache data if needed
-- **Don't use external APIs** - Too slow and unreliable
-- **Don't make generators stateful** - Unless you have a good reason
-- **Don't expose sensitive data** - Ensure anonymization is truly anonymous
-- **Don't make generators too complex** - Keep logic simple
-
----
-
-## Troubleshooting
-
-### Generator Not Found
-
-```ruby
-# Error: No generator for type :custom_type
-
-# Solution: Make sure it's registered
-ColumnAnonymizer::Anonymizer.register(:custom_type) do
-  "CUSTOM-#{SecureRandom.hex(4)}"
-end
-```
-
-### Generator Returns Nil
-
-```ruby
-# Problem: Generator doesn't return a value
-ColumnAnonymizer::Anonymizer.register(:broken) do
-  puts "Oops, no return value"
-  # Missing return!
-end
-
-# Solution: Ensure generator returns a value
-ColumnAnonymizer::Anonymizer.register(:fixed) do
-  "VALUE-#{SecureRandom.hex(4)}"
-end
-```
-
-### Initializer Not Loading
-
-```bash
-# Make sure initializer is in the right place
-ls config/initializers/column_anonymizer.rb
-
-# Restart Rails server after changes
-rails restart
-```
-
----
-
-## Summary
-
-Custom anonymization generators give you:
-
-✅ **Flexibility** - Define domain-specific anonymization  
-✅ **Simplicity** - Easy registration with blocks  
-✅ **Power** - Use Faker, Rails models, or custom logic  
-✅ **Testability** - Easy to test in isolation  
-✅ **Maintainability** - Centralized in initializer  
-
-Start with:
-```bash
-rails generate column_anonymizer:initializer
-```
-
-Then register your custom types and use them in your YAML config! 🚀