column_anonymizer 0.1.0 → 0.2.0

data/CUSTOM_GENERATORS_COMPLETE.md

@@ -1,507 +0,0 @@
-# ✅ Custom Generators Implementation Complete
-
-## 🎯 Your Request
-**"I want a way to add custom anonymization types from within the rails app. I am thinking it would be some ruby class somewhere that would define a custom type then it would get appended when we anonymize the data"**
-
-## ✅ Delivered!
-
-You can now register custom anonymization types from within your Rails app using a simple, flexible API.
-
----
-
-## 📦 What Was Created
-
-### 1. **Enhanced Anonymizer Class**
-**File**: `lib/column_anonymizer/anonymizer.rb`
-
-**New Features:**
-- `register(type, &block)` - Register custom generators
-- `unregister(type)` - Remove custom generators
-- `all_generators` - Get built-in + custom generators merged
-- `generator_exists?(type)` - Check if a generator exists
-- `reset_custom_generators!` - Clear custom generators (for testing)
-- `BUILT_IN_GENERATORS` constant (renamed from `GENERATORS`)
-- `@custom_generators` class instance variable to store custom types
-
-### 2. **Initializer Generator**
-**File**: `lib/generators/column_anonymizer/initializer/initializer_generator.rb`
-
-Command: `rails generate column_anonymizer:initializer`
-
-Creates: `config/initializers/column_anonymizer.rb` with:
-- Example custom generators
-- Helpful comments
-- Common patterns
-- List of built-in types
-
-### 3. **Initializer Template**
-**File**: `lib/generators/column_anonymizer/initializer/templates/column_anonymizer.rb`
-
-Includes examples for:
-- Simple masking (credit cards)
-- Using Faker
-- Custom business logic
-- Format-specific patterns
-- Using Rails models
-- Date/time generators
-- Complex multi-field logic
-
-### 4. **Comprehensive Documentation**
-- `CUSTOM_GENERATORS_GUIDE.md` (500+ lines) - Complete guide
-- `CUSTOM_GENERATORS_QUICK_REF.md` - Quick reference
-- Updated `README.md` - Custom generators section
-- Updated `CHANGELOG.md` - Feature documentation
-
----
-
-## 🚀 How It Works
-
-### Step 1: Generate Initializer
-```bash
-rails generate column_anonymizer:initializer
-```
-
-### Step 2: Register Custom Types
-```ruby
-# config/initializers/column_anonymizer.rb
-
-ColumnAnonymizer::Anonymizer.register(:credit_card) do
-  "XXXX-XXXX-XXXX-#{rand(1000..9999)}"
-end
-
-ColumnAnonymizer::Anonymizer.register(:employee_id) do
-  "EMP-#{Time.now.year}-#{rand(10000..99999)}"
-end
-```
-
-### Step 3: Use in YAML Config
-```yaml
-# config/encrypted_columns.yml
-User:
-  credit_card_number: credit_card  # ← Custom type!
-  employee_number: employee_id     # ← Custom type!
-```
-
-### Step 4: Anonymize
-```ruby
-user = User.first
-ColumnAnonymizer::Anonymizer.anonymize_model!(user)
-
-# credit_card_number => "XXXX-XXXX-XXXX-4823"
-# employee_number => "EMP-2026-47293"
-```
-
----
-
-## 🎨 Registration Patterns
-
-### Block Syntax (Recommended)
-```ruby
-ColumnAnonymizer::Anonymizer.register(:custom_type) do
-  "VALUE-#{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
-
-### Credit Card Masking
-```ruby
-ColumnAnonymizer::Anonymizer.register(:credit_card) do
-  "XXXX-XXXX-XXXX-#{rand(1000..9999)}"
-end
-```
-
-### License Plate
-```ruby
-ColumnAnonymizer::Anonymizer.register(:license_plate) do
-  letters = ('A'..'Z').to_a.sample(3).join
-  numbers = rand(100..999)
-  "#{letters}-#{numbers}"
-end
-```
-
-### Account Number with Format
-```ruby
-ColumnAnonymizer::Anonymizer.register(:account_number) do
-  prefix = "ACC"
-  year = Time.now.year
-  sequence = rand(10000..99999)
-  "#{prefix}#{year}#{sequence}"
-end
-```
-
-### Using Faker
-```ruby
-ColumnAnonymizer::Anonymizer.register(:company_name) do
-  Faker::Company.name
-end
-```
-
-### From Database
-```ruby
-ColumnAnonymizer::Anonymizer.register(:department_name) do
-  Department.active.pluck(:name).sample || "General"
-end
-```
-
----
-
-## 🔧 API Reference
-
-### Register a Generator
-```ruby
-ColumnAnonymizer::Anonymizer.register(type, generator = nil, &block)
-
-# With block
-register(:type) { "value" }
-
-# With lambda
-register(:type, -> { "value" })
-
-# With callable
-register(:type, MyGenerator)
-```
-
-### Unregister a Generator
-```ruby
-ColumnAnonymizer::Anonymizer.unregister(:type)
-```
-
-### Check if Generator Exists
-```ruby
-ColumnAnonymizer::Anonymizer.generator_exists?(:type)
-# => true/false
-```
-
-### Get All Generators
-```ruby
-ColumnAnonymizer::Anonymizer.all_generators
-# => { email: #<Proc>, phone: #<Proc>, credit_card: #<Proc>, ... }
-```
-
-### Reset Custom Generators (Testing)
-```ruby
-ColumnAnonymizer::Anonymizer.reset_custom_generators!
-```
-
----
-
-## 🧪 How Custom Generators Merge
-
-### Built-in Generators
-```ruby
-BUILT_IN_GENERATORS = {
-  email: -> { Faker::Internet.email },
-  phone: -> { Faker::PhoneNumber.phone_number },
-  ssn: -> { Faker::IdNumber.ssn_valid },
-  name: -> { Faker::Name.name },
-  first_name: -> { Faker::Name.first_name },
-  last_name: -> { Faker::Name.last_name },
-  address: -> { Faker::Address.full_address },
-  text: -> { Faker::Lorem.paragraph }
-}
-```
-
-### Custom Generators
-```ruby
-@custom_generators = {
-  credit_card: -> { "XXXX-XXXX-XXXX-#{rand(1000..9999)}" },
-  employee_id: -> { "EMP-#{Time.now.year}-#{rand(10000..99999)}" }
-}
-```
-
-### Merged (all_generators)
-```ruby
-{
-  # Built-ins
-  email: -> { ... },
-  phone: -> { ... },
-  ssn: -> { ... },
-  name: -> { ... },
-  first_name: -> { ... },
-  last_name: -> { ... },
-  address: -> { ... },
-  text: -> { ... },
-  
-  # Custom
-  credit_card: -> { ... },
-  employee_id: -> { ... }
-}
-```
-
----
-
-## 🔄 Complete Workflow
-
-### 1. Setup
-```bash
-# Install gem
-echo "gem 'column_anonymizer'" >> Gemfile
-bundle install
-
-# Generate config
-rails g column_anonymizer:install --scan
-
-# Generate initializer for custom types
-rails g column_anonymizer:initializer
-```
-
-### 2. Define Custom Types
-```ruby
-# config/initializers/column_anonymizer.rb
-
-ColumnAnonymizer::Anonymizer.register(:credit_card) do
-  "XXXX-XXXX-XXXX-#{rand(1000..9999)}"
-end
-
-ColumnAnonymizer::Anonymizer.register(:employee_id) do
-  "EMP-#{Time.now.year}-#{rand(10000..99999)}"
-end
-
-ColumnAnonymizer::Anonymizer.register(:medical_record) do
-  "MRN#{rand(100000..999999)}"
-end
-```
-
-### 3. Configure YAML
-```yaml
-# config/encrypted_columns.yml
-User:
-  email: email                    # Built-in
-  credit_card_number: credit_card # Custom!
-
-Employee:
-  employee_number: employee_id    # Custom!
-  ssn: ssn                        # Built-in
-
-Patient:
-  medical_record_number: medical_record  # Custom!
-```
-
-### 4. Use in Models
-```ruby
-class User < ApplicationRecord
-  encrypts :email
-  encrypts :credit_card_number
-end
-
-class Employee < ApplicationRecord
-  encrypts :employee_number
-  encrypts :ssn
-end
-
-class Patient < ApplicationRecord
-  encrypts :medical_record_number
-end
-```
-
-### 5. Anonymize
-```ruby
-user = User.first
-ColumnAnonymizer::Anonymizer.anonymize_model!(user)
-
-# Before:
-# email: "john@example.com"
-# credit_card_number: "4532-1234-5678-9012"
-
-# After:
-# email: "user_abc123@example.com"
-# credit_card_number: "XXXX-XXXX-XXXX-7482"
-```
-
----
-
-## ✨ Benefits
-
-### Flexibility
-- ✅ Define any custom format
-- ✅ Use Faker, Rails models, or custom logic
-- ✅ Domain-specific anonymization
-
-### Simplicity
-- ✅ Easy registration with blocks
-- ✅ No complex class hierarchy
-- ✅ Just define and use
-
-### Power
-- ✅ Access to full Ruby/Rails environment
-- ✅ Can use database queries
-- ✅ Can use external libraries
-
-### Maintainability
-- ✅ All custom types in one place (initializer)
-- ✅ Easy to test
-- ✅ Clear separation from built-ins
-
----
-
-## 🧪 Testing
-
-```ruby
-# spec/initializers/column_anonymizer_spec.rb
-
-RSpec.describe "Custom Anonymizers" do
-  before do
-    ColumnAnonymizer::Anonymizer.reset_custom_generators!
-    
-    ColumnAnonymizer::Anonymizer.register(:credit_card) do
-      "XXXX-XXXX-XXXX-#{rand(1000..9999)}"
-    end
-  end
-
-  it "registers custom generator" do
-    expect(ColumnAnonymizer::Anonymizer.generator_exists?(:credit_card)).to be true
-  end
-
-  it "generates correct format" do
-    generator = ColumnAnonymizer::Anonymizer.all_generators[:credit_card]
-    result = generator.call
-    
-    expect(result).to match(/^XXXX-XXXX-XXXX-\d{4}$/)
-  end
-
-  it "merges with built-in generators" do
-    generators = ColumnAnonymizer::Anonymizer.all_generators
-    
-    expect(generators).to include(:email, :phone, :credit_card)
-  end
-end
-```
-
----
-
-## 📊 Technical Implementation
-
-### Class Structure
-```ruby
-class Anonymizer
-  # Built-in generators (frozen)
-  BUILT_IN_GENERATORS = { ... }.freeze
-  
-  # Custom generators (mutable)
-  @custom_generators = {}
-  
-  class << self
-    # Registration API
-    def register(type, generator = nil, &block)
-      # Store in @custom_generators
-    end
-    
-    # Merge built-in + custom
-    def all_generators
-      BUILT_IN_GENERATORS.merge(@custom_generators)
-    end
-    
-    # Use merged generators
-    def anonymize_model(model_instance)
-      generators = all_generators
-      # Use generators[column_type]
-    end
-  end
-end
-```
-
-### Flow
-```
-1. Rails boots
-2. Initializer loads (config/initializers/column_anonymizer.rb)
-3. Custom generators registered via .register()
-4. Stored in @custom_generators
-5. When anonymizing:
-   - all_generators called
-   - BUILT_IN_GENERATORS.merge(@custom_generators)
-   - Merged hash used for anonymization
-6. Custom types override built-ins if same key
-```
-
----
-
-## 📚 Documentation
-
-### Created
-1. **CUSTOM_GENERATORS_GUIDE.md** (500+ lines)
-   - Complete guide with examples
-   - All registration patterns
-   - Advanced use cases
-   - Best practices
-   - Troubleshooting
-
-2. **CUSTOM_GENERATORS_QUICK_REF.md**
-   - One-page reference
-   - Common patterns
-   - API methods
-   - Quick examples
-
-3. **README.md** - Updated
-   - Custom generators section
-   - Quick example
-   - Link to full guide
-
-4. **CHANGELOG.md** - Updated
-   - Feature documented
-   - API listed
-   - Changes noted
-
----
-
-## 🎉 Summary
-
-You can now add custom anonymization types easily:
-
-### Command
-```bash
-rails generate column_anonymizer:initializer
-```
-
-### Register
-```ruby
-ColumnAnonymizer::Anonymizer.register(:custom_type) do
-  # Your anonymization logic
-end
-```
-
-### Use
-```yaml
-Model:
-  column: custom_type
-```
-
-**Simple, powerful, and flexible!** 🚀
-
----
-
-## 📦 Files Summary
-
-| File | Purpose |
-|------|---------|
-| `lib/column_anonymizer/anonymizer.rb` | Enhanced with registration API |
-| `lib/generators/.../initializer_generator.rb` | Generator command |
-| `lib/generators/.../templates/column_anonymizer.rb` | Template with examples |
-| `CUSTOM_GENERATORS_GUIDE.md` | Complete documentation |
-| `CUSTOM_GENERATORS_QUICK_REF.md` | Quick reference |
-| `README.md` | Updated with custom generators |
-| `CHANGELOG.md` | Feature documented |
-
----
-
-**Status:** ✅ **COMPLETE AND READY TO USE**  
-**Date:** February 5, 2026  
-**Implementation:** Custom generator registration system