column_anonymizer 0.1.0

data/WORKFLOW_GUIDE.md

@@ -0,0 +1,368 @@
+# Column Anonymizer - Workflow Guide
+
+## 🎯 Quick Reference
+
+### Installation Options
+
+#### Option 1: Install + Auto-Scan (Recommended) ⭐
+```bash
+rails generate column_anonymizer:install --scan
+```
+**What happens:**
+1. Creates `config/encrypted_columns.yml`
+2. Scans all models for `encrypts` calls
+3. Populates YAML with detected columns
+4. Ready to use immediately!
+
+#### Option 2: Install Then Scan Separately
+```bash
+rails generate column_anonymizer:install
+rails generate column_anonymizer:scan
+```
+**What happens:**
+1. Creates empty `config/encrypted_columns.yml` template
+2. Then scans and populates it
+3. Same result as Option 1
+
+#### Option 3: Manual Configuration
+```bash
+rails generate column_anonymizer:install
+# Edit config/encrypted_columns.yml manually
+```
+**What happens:**
+1. Creates `config/encrypted_columns.yml` template
+2. You manually add all models and columns
+3. More control, more work
+
+---
+
+## 📊 Workflow Diagrams
+
+### Auto-Scan Workflow (Recommended)
+
+```
+┌─────────────────────────────────────────────────────┐
+│  rails generate column_anonymizer:install --scan    │
+└─────────────────────┬───────────────────────────────┘
+                      │
+                      ▼
+         ┌────────────────────────┐
+         │ Create config file     │
+         │ config/encrypted_      │
+         │ columns.yml            │
+         └────────┬───────────────┘
+                  │
+                  ▼
+         ┌────────────────────────┐
+         │ Scan app/models/       │
+         │ directory              │
+         └────────┬───────────────┘
+                  │
+                  ▼
+         ┌────────────────────────┐
+         │ Find all 'encrypts'    │
+         │ method calls           │
+         └────────┬───────────────┘
+                  │
+                  ▼
+         ┌────────────────────────┐
+         │ Guess column types     │
+         │ based on names         │
+         └────────┬───────────────┘
+                  │
+                  ▼
+         ┌────────────────────────┐
+         │ Update YAML config     │
+         │ with discovered        │
+         │ columns                │
+         └────────┬───────────────┘
+                  │
+                  ▼
+         ┌────────────────────────┐
+         │ ✅ Ready to anonymize! │
+         └────────────────────────┘
+```
+
+### Manual Configuration Workflow
+
+```
+┌─────────────────────────────────────┐
+│  rails generate                      │
+│  column_anonymizer:install          │
+└────────────┬────────────────────────┘
+             │
+             ▼
+    ┌────────────────────┐
+    │ Create empty       │
+    │ config file        │
+    └────────┬───────────┘
+             │
+             ▼
+    ┌────────────────────┐
+    │ Manually edit      │
+    │ YAML file          │
+    │ (tedious!)         │
+    └────────┬───────────┘
+             │
+             ▼
+    ┌────────────────────┐
+    │ Add each model     │
+    │ and column         │
+    │ by hand            │
+    └────────┬───────────┘
+             │
+             ▼
+    ┌────────────────────┐
+    │ Ready to use       │
+    └────────────────────┘
+```
+
+---
+
+## 🔄 Adding New Encrypted Columns
+
+### When You Add New Models
+
+```ruby
+# 1. Create a new model with encrypted attributes
+class Patient < ApplicationRecord
+  encrypts :medical_record_number
+  encrypts :emergency_contact_phone
+end
+
+# 2. Run the scanner
+# rails generate column_anonymizer:scan
+
+# 3. Output shows:
+# 🔍 Scanning models...
+# ℹ️  Skipping User.email (already configured)
+# ➕ Adding Patient.medical_record_number as 'text'
+# ➕ Adding Patient.emergency_contact_phone as 'phone'
+# ✅ Updated config/encrypted_columns.yml
+```
+
+### Smart Merging
+
+The scanner **never overwrites** existing configuration:
+
+```yaml
+# Before scan:
+User:
+  email: email  # ← Stays as-is
+
+# After adding new Patient model and running scan:
+User:
+  email: email  # ← Preserved!
+
+Patient:
+  medical_record_number: text  # ← Added
+  emergency_contact_phone: phone  # ← Added
+```
+
+---
+
+## 🧠 Type Guessing Examples
+
+### Common Column Names → Auto-Detected Types
+
+```ruby
+class User < ApplicationRecord
+  encrypts :email                    # → type: email
+  encrypts :phone_number             # → type: phone
+  encrypts :mobile                   # → type: phone
+  encrypts :ssn                      # → type: ssn
+  encrypts :social_security_number   # → type: ssn
+  encrypts :first_name               # → type: first_name
+  encrypts :last_name                # → type: last_name
+  encrypts :full_name                # → type: name
+  encrypts :home_address             # → type: address
+  encrypts :street_address           # → type: address
+  encrypts :credit_card_number       # → type: text
+  encrypts :api_token                # → type: text
+  encrypts :password_digest          # → type: text
+  encrypts :custom_field             # → type: text (default)
+end
+```
+
+### Resulting YAML
+
+```yaml
+User:
+  email: email
+  phone_number: phone
+  mobile: phone
+  ssn: ssn
+  social_security_number: ssn
+  first_name: first_name
+  last_name: last_name
+  full_name: name
+  home_address: address
+  street_address: address
+  credit_card_number: text
+  api_token: text
+  password_digest: text
+  custom_field: text
+```
+
+---
+
+## 🎨 Customizing Auto-Detected Types
+
+You can always override the auto-detected types:
+
+```bash
+# 1. Run scanner
+rails generate column_anonymizer:scan
+
+# 2. Review config/encrypted_columns.yml
+
+# 3. Manually adjust any incorrect guesses
+```
+
+**Example:**
+
+```yaml
+# Auto-detected (might be wrong):
+User:
+  contact_info: text  # ← Guessed 'text'
+
+# Manually corrected:
+User:
+  contact_info: phone  # ← You know it's a phone number
+```
+
+---
+
+## 📝 Complete Example
+
+### Step-by-Step
+
+```bash
+# 1. Add gem to Gemfile
+echo "gem 'column_anonymizer'" >> Gemfile
+bundle install
+
+# 2. Install with auto-scan
+rails generate column_anonymizer:install --scan
+
+# Output:
+# ✅ Created config/encrypted_columns.yml
+# 🔍 Scanning models for encrypted attributes...
+#    ➕ Adding User.email as 'email'
+#    ➕ Adding User.phone as 'phone'
+#    ➕ Adding User.ssn as 'ssn'
+# ✅ Scanned 1 model(s)
+# 📝 Updated config/encrypted_columns.yml
+
+# 3. Check the config
+cat config/encrypted_columns.yml
+
+# Output:
+# ---
+# User:
+#   email: email
+#   phone: phone
+#   ssn: ssn
+
+# 4. Anonymize data
+rails console
+```
+
+```ruby
+# In console:
+user = User.first
+ColumnAnonymizer::Anonymizer.anonymize_model!(user)
+user.reload
+
+puts user.email  # => "user_abc12345@example.com"
+puts user.phone  # => "+15551234567"
+puts user.ssn    # => "123-45-6789"
+```
+
+---
+
+## 🚀 Pro Tips
+
+### Tip 1: Run Scan After Model Changes
+```bash
+# After adding encrypts to existing models
+rails generate column_anonymizer:scan
+# Only new columns are added
+```
+
+### Tip 2: Review Auto-Detections
+```bash
+# Always review the generated YAML
+cat config/encrypted_columns.yml
+# Adjust types if needed
+```
+
+### Tip 3: Use in CI/CD
+```bash
+# Add to your deployment script
+rails generate column_anonymizer:scan --quiet
+# Keeps config in sync with models
+```
+
+### Tip 4: Safe to Run Multiple Times
+```bash
+# No risk of data loss
+rails generate column_anonymizer:scan
+rails generate column_anonymizer:scan
+rails generate column_anonymizer:scan
+# Always safe - never overwrites!
+```
+
+---
+
+## ⚡ Quick Command Reference
+
+| Command | What It Does | When to Use |
+|---------|--------------|-------------|
+| `rails g column_anonymizer:install --scan` | Install + auto-configure | First time setup ⭐ |
+| `rails g column_anonymizer:scan` | Update config with new models | After adding encrypts |
+| `rails g column_anonymizer:install` | Install empty config | Manual configuration |
+| `ColumnAnonymizer::SchemaLoader.reload_schema!` | Reload in console | Development/testing |
+
+---
+
+## 🎯 Decision Tree
+
+```
+Do you have models with 'encrypts' already?
+│
+├─ YES → Use: rails g column_anonymizer:install --scan ⭐
+│         (Fastest! Everything auto-configured)
+│
+└─ NO → Use: rails g column_anonymizer:install
+          Then add encrypts to models
+          Then run: rails g column_anonymizer:scan
+```
+
+---
+
+## 📚 Related Files
+
+- `README.md` - Complete documentation
+- `IMPLEMENTATION_SUMMARY.md` - Technical details
+- `SCAN_GENERATOR_TEST.md` - Testing guide
+- `YAML_MIGRATION_GUIDE.md` - Migration from old approach
+- `CHANGELOG.md` - Version history
+
+---
+
+## 🎉 Summary
+
+**Before this feature:**
+- Manual YAML editing required
+- Prone to typos and errors
+- Time-consuming setup
+
+**After this feature:**
+- One command: `rails g column_anonymizer:install --scan`
+- Automatic discovery and configuration
+- Intelligent type detection
+- Safe to run multiple times
+- Ready to use in seconds!
+
+**The Power of Automation!** 🚀

data/YAML_MIGRATION_GUIDE.md

@@ -0,0 +1,284 @@
+# Column Encrypter Gem - YAML-Based Configuration
+
+## ✅ Gem Successfully Refactored!
+
+The gem has been refactored from method-based configuration to YAML-based configuration.
+
+## 🎯 Key Changes
+
+### Before (Method-Based):
+```ruby
+class User < ApplicationRecord
+  encrypts_with_type :email, :email
+  encrypts_with_type :phone_number, :phone
+end
+```
+
+### After (YAML-Based):
+```yaml
+# config/encrypted_columns.yml
+User:
+  email: email
+  phone_number: phone
+```
+
+```ruby
+class User < ApplicationRecord
+  encrypts :email
+  encrypts :phone_number
+end
+```
+
+## 📁 Gem Structure
+
+```
+column_anonymizer/
+├── lib/
+│   ├── column_anonymizer.rb                     # Main entry point
+│   ├── column_anonymizer/
+│   │   ├── version.rb                           # Version: 0.1.0
+│   │   ├── schema_loader.rb                     # Loads YAML configuration
+│   │   ├── encryptable.rb                       # Reads types from YAML
+│   │   ├── anonymizer.rb                        # Data anonymization
+│   │   └── railtie.rb                           # Rails integration
+│   └── generators/
+│       └── column_anonymizer/
+│           ├── install/
+│           │   ├── install_generator.rb          # Rails generator
+│           │   ├── templates/
+│           │   │   └── encrypted_columns.yml    # YAML template
+│           │   └── README                        # Installation instructions
+│           └── scan/
+│               └── scan_generator.rb             # ⭐ Auto-discovery scanner
+├── spec/
+│   ├── column_anonymizer_spec.rb                # Tests
+│   └── spec_helper.rb                          # Test configuration
+├── column_anonymizer.gemspec                    # Gem specification
+├── Gemfile                                     # Dependencies
+├── Rakefile                                    # Rake tasks
+├── README.md                                   # Documentation
+└── CHANGELOG.md                                # Version history
+```
+
+## 🚀 Installation & Usage
+
+### 1. Install the Gem
+
+```bash
+# Add to Gemfile
+gem 'column_encrypter', path: '/Users/hkend/Documents/column_encrypter/column_encrypter'
+
+# Or install locally
+cd /Users/hkend/Documents/column_encrypter/column_encrypter
+gem build column_encrypter.gemspec
+gem install column_encrypter-0.1.0.gem
+```
+
+### 2. Generate Configuration File
+
+```bash
+rails generate column_anonymizer:install
+```
+
+This creates `config/encrypted_columns.yml`.
+
+### 3. Define Your Schema
+
+**Option A: Automatic Scanning (Recommended)**
+
+The gem can automatically scan your models and populate the YAML file:
+
+```bash
+# Scan existing models and update config
+rails generate column_anonymizer:scan
+
+# Or install and scan in one step
+rails generate column_anonymizer:install --scan
+```
+
+The scanner will:
+- Find all models with `encrypts` calls
+- Intelligently guess the data type based on column names
+- Add new columns to your config without overwriting existing entries
+- Show you what was discovered
+
+**Option B: Manual Configuration**
+
+Edit `config/encrypted_columns.yml`:
+
+```yaml
+User:
+  email: email
+  phone_number: phone
+  ssn: ssn
+  full_name: name
+
+Account:
+  bank_account_number: text
+  routing_number: text
+```
+
+### 4. Use Standard Rails Encryption
+
+```ruby
+class User < ApplicationRecord
+  encrypts :email
+  encrypts :phone_number
+  encrypts :ssn
+  encrypts :full_name
+end
+```
+
+### 5. Anonymize Data
+
+```ruby
+# In console or rake task
+user = User.first
+ColumnEncrypter::Anonymizer.anonymize_model!(user)
+
+# email becomes: user_a1b2c3d4@example.com
+# phone_number becomes: +15551234567
+# ssn becomes: 123-45-6789
+# full_name becomes: Anonymous User abc123
+```
+
+## 🎨 Built-in Generators
+
+| Type | Example Output |
+|------|----------------|
+| `:email` | `user_a1b2c3d4@example.com` |
+| `:phone` | `+15551234567` |
+| `:ssn` | `123-45-6789` |
+| `:name` | `Anonymous User abc123` |
+| `:first_name` | `John`, `Jane`, `Alex` |
+| `:last_name` | `Smith`, `Johnson` |
+| `:address` | `1234 Anonymous St, City, ST 12345` |
+| `:text` | `Anonymized text a1b2c3d4` |
+
+## 🧠 Intelligent Type Guessing
+
+When you use `rails generate column_anonymizer:scan`, the generator intelligently guesses the data type based on column names:
+
+| Column Name Pattern | Detected Type |
+|---------------------|---------------|
+| `email` | `:email` |
+| `phone`, `mobile`, `cell`, `telephone` | `:phone` |
+| `ssn`, `social_security` | `:ssn` |
+| `first_name`, `fname` | `:first_name` |
+| `last_name`, `lname`, `surname` | `:last_name` |
+| `name`, `full_name`, `fullname` | `:name` |
+| `address`, `street`, `addr` | `:address` |
+| `card_number`, `credit_card`, `cvv`, `cvc` | `:text` |
+| `password`, `token`, `secret` | `:text` |
+| Everything else | `:text` |
+
+You can always manually adjust the types in `config/encrypted_columns.yml` after scanning.
+
+## ✨ Benefits of YAML Approach
+
+1. **Centralized Configuration**: All column types in one place
+2. **No Code Changes**: Just use standard Rails `encrypts` method
+3. **Easy Updates**: Modify schema without touching model files
+4. **Automatic Discovery**: Scan feature finds encrypted columns automatically
+5. **Smart Type Guessing**: Intelligently detects appropriate anonymization types
+4. **Better Organization**: Clear overview of all encrypted columns
+5. **Version Control Friendly**: YAML changes are easy to review
+
+## 🔄 Schema Reloading (Development)
+
+```ruby
+# In Rails console
+ColumnEncrypter::SchemaLoader.reload_schema!
+User.reload_encrypted_columns_metadata!
+```
+
+## 📝 Example YAML Schema
+
+```yaml
+# config/encrypted_columns.yml
+
+User:
+  email: email
+  phone_number: phone
+  ssn: ssn
+  first_name: first_name
+  last_name: last_name
+  home_address: address
+  date_of_birth: text
+
+Patient:
+  medical_record_number: text
+  ssn: ssn
+  emergency_contact_phone: phone
+  email: email
+
+CreditCard:
+  card_number: text
+  cvv: text
+  cardholder_name: name
+  billing_address: address
+```
+
+## 🧪 Testing in Rails Console
+
+```bash
+# Add gem to your Rails app's Gemfile
+gem 'column_encrypter', path: '/Users/hkend/Documents/column_encrypter/column_encrypter'
+
+bundle install
+rails generate column_encrypter:install
+rails console
+```
+
+Then in console:
+
+```ruby
+# Create the schema
+File.write('config/encrypted_columns.yml', <<~YAML)
+  User:
+    email: email
+    phone: phone
+YAML
+
+# Reload schema
+ColumnEncrypter::SchemaLoader.reload_schema!
+
+# Check metadata
+User.encrypted_columns_metadata
+# => {:email=>:email, :phone=>:phone}
+
+# Anonymize
+user = User.first
+ColumnEncrypter::Anonymizer.anonymize_model!(user)
+```
+
+## 📦 Files Created
+
+- ✅ `lib/column_encrypter.rb` - Main entry point
+- ✅ `lib/column_encrypter/version.rb` - Version
+- ✅ `lib/column_encrypter/schema_loader.rb` - YAML loader
+- ✅ `lib/column_encrypter/encryptable.rb` - ActiveRecord integration
+- ✅ `lib/column_encrypter/anonymizer.rb` - Data generators
+- ✅ `lib/column_encrypter/railtie.rb` - Rails auto-loading
+- ✅ `lib/generators/column_encrypter/install/install_generator.rb` - Generator
+- ✅ `lib/generators/column_encrypter/install/templates/encrypted_columns.yml` - Template
+- ✅ `lib/generators/column_encrypter/install/README` - Install instructions
+- ✅ `spec/column_encrypter_spec.rb` - Tests
+- ✅ `spec/spec_helper.rb` - Test configuration
+- ✅ `column_encrypter.gemspec` - Gem specification
+- ✅ `Gemfile` - Dependencies
+- ✅ `Rakefile` - Rake tasks
+- ✅ `README.md` - Complete documentation
+- ✅ `CHANGELOG.md` - Version history
+
+## 🎉 Ready to Use!
+
+The gem is complete with YAML-based configuration. You can now:
+
+1. Install it in your Rails app
+2. Run `rails generate column_encrypter:install`
+3. Define your schema in `config/encrypted_columns.yml`
+4. Use standard Rails `encrypts` method
+5. Anonymize data with `ColumnEncrypter::Anonymizer.anonymize_model!(record)`
+
+**Location:** `/Users/hkend/Documents/column_encrypter/column_encrypter/`