opaque_id 1.4.0 → 1.6.0

data/tasks/references/opaque_gem_requirements.md

@@ -1,482 +0,0 @@
-# OpaqueId Gem - Complete File Structure
-
-## File Structure
-
-```
-opaque_id/
-├── lib/
-│   ├── opaque_id.rb                 # Main module with generator
-│   ├── opaque_id/
-│   │   ├── version.rb               # Version constant
-│   │   └── model.rb                 # ActiveRecord concern
-│   └── generators/
-│       └── opaque_id/
-│           ├── install_generator.rb  # Migration generator
-│           └── templates/
-│               └── migration.rb.tt   # Migration template
-├── spec/
-│   ├── spec_helper.rb
-│   ├── opaque_id_spec.rb
-│   └── opaque_id/
-│       └── model_spec.rb
-├── opaque_id.gemspec
-├── Gemfile
-├── Rakefile
-├── README.md
-├── LICENSE.txt
-└── CHANGELOG.md
-```
-
-## opaque_id.gemspec
-
-```ruby
-# frozen_string_literal: true
-
-require_relative "lib/opaque_id/version"
-
-Gem::Specification.new do |spec|
-  spec.name = "opaque_id"
-  spec.version = OpaqueId::VERSION
-  spec.authors = ["Your Name"]
-  spec.email = ["your.email@example.com"]
-
-  spec.summary = "Generate cryptographically secure, collision-free opaque IDs for ActiveRecord models"
-  spec.description = <<~DESC
-    OpaqueId provides a simple way to generate unique, URL-friendly identifiers for your ActiveRecord models.
-    Uses rejection sampling for unbiased random generation, ensuring perfect uniformity across the alphabet.
-    Prevents exposing incremental database IDs in URLs and APIs.
-  DESC
-  spec.homepage = "https://github.com/yourusername/opaque_id"
-  spec.license = "MIT"
-  spec.required_ruby_version = ">= 2.7.0"
-
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/yourusername/opaque_id"
-  spec.metadata["changelog_uri"] = "https://github.com/yourusername/opaque_id/blob/main/CHANGELOG.md"
-
-  spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|circleci)|appveyor)})
-    end
-  end
-
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  # Dependencies
-  spec.add_dependency "activerecord", ">= 6.0"
-  spec.add_dependency "activesupport", ">= 6.0"
-
-  # Development dependencies
-  spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
-  spec.add_development_dependency "sqlite3", "~> 1.4"
-  spec.add_development_dependency "rubocop", "~> 1.21"
-end
-```
-
-## Gemfile
-
-```ruby
-# frozen_string_literal: true
-
-source "https://rubygems.org"
-
-gemspec
-
-gem "rake", "~> 13.0"
-gem "rspec", "~> 3.0"
-gem "sqlite3", "~> 1.4"
-gem "rubocop", "~> 1.21"
-```
-
-## Rakefile
-
-```ruby
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-require "rubocop/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-RuboCop::RakeTask.new
-
-task default: %i[spec rubocop]
-```
-
-## lib/opaque_id.rb (Entry Point)
-
-```ruby
-# frozen_string_literal: true
-
-require "securerandom"
-require_relative "opaque_id/version"
-require_relative "opaque_id/model"
-
-module OpaqueId
-  class Error < StandardError; end
-  class GenerationError < Error; end
-  class ConfigurationError < Error; end
-
-  # Standard URL-safe alphabet (64 characters)
-  STANDARD_ALPHABET = "_-0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
-
-  # Lowercase alphanumeric (36 characters)
-  ALPHANUMERIC_ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz"
-
-  class << self
-    # Generate a cryptographically secure random ID
-    def generate(size: 21, alphabet: ALPHANUMERIC_ALPHABET)
-      raise ConfigurationError, "Size must be positive" unless size.positive?
-      raise ConfigurationError, "Alphabet cannot be empty" if alphabet.empty?
-
-      alphabet_size = alphabet.size
-      return generate_fast(size, alphabet) if alphabet_size == 64
-
-      generate_unbiased(size, alphabet, alphabet_size)
-    end
-
-    private
-
-    def generate_fast(size, alphabet)
-      bytes = SecureRandom.random_bytes(size).bytes
-      size.times.map { |i| alphabet[bytes[i] & 63] }.join
-    end
-
-    def generate_unbiased(size, alphabet, alphabet_size)
-      mask = (2 << Math.log2(alphabet_size - 1).floor) - 1
-      step = (1.6 * mask * size / alphabet_size).ceil
-      id = String.new(capacity: size)
-
-      loop do
-        bytes = SecureRandom.random_bytes(step).bytes
-        bytes.each do |byte|
-          masked_byte = byte & mask
-          if masked_byte < alphabet_size
-            id << alphabet[masked_byte]
-            return id if id.size == size
-          end
-        end
-      end
-    end
-  end
-end
-```
-
-## lib/generators/opaque_id/install_generator.rb
-
-```ruby
-# frozen_string_literal: true
-
-require "rails/generators"
-require "rails/generators/active_record"
-
-module OpaqueId
-  module Generators
-    class InstallGenerator < Rails::Generators::Base
-      include ActiveRecord::Generators::Migration
-
-      source_root File.expand_path("templates", __dir__)
-
-      argument :table_name, type: :string, default: nil, banner: "table_name"
-
-      class_option :column_name, type: :string, default: "opaque_id",
-                   desc: "Name of the column to add"
-
-      def create_migration_file
-        if table_name.present?
-          migration_template "migration.rb.tt",
-                             "db/migrate/add_opaque_id_to_#{table_name}.rb"
-        else
-          say "Usage: rails generate opaque_id:install TABLE_NAME", :red
-          say "Example: rails generate opaque_id:install posts", :green
-        end
-      end
-    end
-  end
-end
-```
-
-## lib/generators/opaque_id/templates/migration.rb.tt
-
-```ruby
-class AddOpaqueIdTo<%= table_name.camelize %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
-  def change
-    add_column :<%= table_name %>, :<%= options[:column_name] %>, :string
-    add_index :<%= table_name %>, :<%= options[:column_name] %>, unique: true
-  end
-end
-```
-
-## README.md
-
-````markdown
-# OpaqueId
-
-Generate cryptographically secure, collision-free opaque IDs for your ActiveRecord models. Perfect for exposing public identifiers in URLs and APIs without revealing your database's internal structure.
-
-## Features
-
-- 🔒 **Cryptographically secure** - Uses Ruby's `SecureRandom` for entropy
-- 🎯 **Unbiased generation** - Implements rejection sampling for perfect uniformity
-- ⚡ **Performance optimized** - Fast path for 64-character alphabets
-- 🎨 **Highly configurable** - Customize alphabet, length, and behavior per model
-- ✅ **HTML-valid by default** - IDs start with letters for use as HTML element IDs
-- 🔄 **Collision detection** - Automatic retry logic with configurable attempts
-- 🚀 **Zero dependencies** - Only requires ActiveSupport/ActiveRecord
-
-## Installation
-
-Add to your Gemfile:
-
-```ruby
-gem 'opaque_id'
-```
-````
-
-Then run:
-
-```bash
-bundle install
-rails generate opaque_id:install posts
-rails db:migrate
-```
-
-## Usage
-
-### Basic Usage
-
-```ruby
-class Post < ApplicationRecord
-  include OpaqueId::Model
-end
-
-post = Post.create(title: "Hello World")
-post.opaque_id #=> "k3x9m2n8p5q7r4t6"
-```
-
-### Custom Configuration
-
-```ruby
-class Invoice < ApplicationRecord
-  include OpaqueId::Model
-
-  self.opaque_id_column = :public_id          # Custom column name
-  self.opaque_id_length = 24                  # Longer IDs
-  self.opaque_id_alphabet = OpaqueId::STANDARD_ALPHABET  # 64-char alphabet
-  self.opaque_id_require_letter_start = false # Allow starting with numbers
-  self.opaque_id_purge_chars = %w[0 1 5 o O i I l]  # Exclude confusing chars
-  self.opaque_id_max_retry = 2000            # More collision attempts
-end
-```
-
-### Standalone Generation
-
-```ruby
-# Generate a random ID
-OpaqueId.generate #=> "k3x9m2n8p5q7r4t6"
-
-# Custom size
-OpaqueId.generate(size: 32) #=> "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
-
-# Custom alphabet
-OpaqueId.generate(
-  size: 21,
-  alphabet: OpaqueId::STANDARD_ALPHABET
-) #=> "V-x3_Kp9Mq2Nn8Rt6Wz4"
-```
-
-### Finding Records
-
-```ruby
-Post.find_by_opaque_id("k3x9m2n8p5q7r4t6")
-Post.find_by_opaque_id!("k3x9m2n8p5q7r4t6") # Raises if not found
-```
-
-## Configuration Options
-
-| Option                           | Default      | Description                  |
-| -------------------------------- | ------------ | ---------------------------- |
-| `opaque_id_column`               | `:opaque_id` | Database column name         |
-| `opaque_id_length`               | `18`         | Length of generated IDs      |
-| `opaque_id_alphabet`             | `0-9a-z`     | Character set for IDs        |
-| `opaque_id_require_letter_start` | `true`       | Ensure HTML validity         |
-| `opaque_id_purge_chars`          | `nil`        | Characters to exclude        |
-| `opaque_id_max_retry`            | `1000`       | Max collision retry attempts |
-
-## Alphabets
-
-### ALPHANUMERIC_ALPHABET (default)
-
-- **Characters**: `0123456789abcdefghijklmnopqrstuvwxyz`
-- **Size**: 36 characters
-- **Use case**: User-facing IDs, URLs
-
-### STANDARD_ALPHABET
-
-- **Characters**: `_-0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ`
-- **Size**: 64 characters
-- **Use case**: Maximum entropy, API keys
-
-## Algorithm
-
-OpaqueId uses **rejection sampling** to ensure perfectly uniform distribution:
-
-1. Calculate optimal bit mask based on alphabet size
-2. Generate random bytes using `SecureRandom`
-3. Apply mask and check if value is within alphabet range
-4. Accept valid values, reject others (no modulo bias)
-
-For 64-character alphabets, uses optimized bitwise operations (`byte & 63`).
-
-## Performance
-
-Benchmarks on Ruby 3.3 (1M iterations):
-
-```
-Standard alphabet (64 chars):  ~1.2M IDs/sec
-Alphanumeric (36 chars):       ~180K IDs/sec
-Custom alphabet (20 chars):    ~150K IDs/sec
-```
-
-## Why OpaqueId?
-
-### The Problem
-
-```ruby
-# ❌ Exposes database structure
-GET /api/posts/1
-GET /api/posts/2  # Easy to enumerate
-
-# ❌ Reveals business metrics
-GET /api/invoices/10523  # "They have 10,523 invoices"
-```
-
-### The Solution
-
-```ruby
-# ✅ Opaque, non-sequential IDs
-GET /api/posts/k3x9m2n8p5q7r4
-GET /api/posts/t6v8w1x4y7z9a2
-
-# ✅ No information leakage
-GET /api/invoices/m3n8p5q7r4t6v8
-```
-
-## License
-
-MIT License - see LICENSE.txt
-
-## Contributing
-
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
-
-````
-
-## spec/spec_helper.rb
-
-```ruby
-# frozen_string_literal: true
-
-require "opaque_id"
-require "active_record"
-
-ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
-
-ActiveRecord::Schema.define do
-  create_table :test_models, force: true do |t|
-    t.string :opaque_id
-    t.timestamps
-  end
-
-  add_index :test_models, :opaque_id, unique: true
-end
-
-class TestModel < ActiveRecord::Base
-  include OpaqueId::Model
-end
-
-RSpec.configure do |config|
-  config.expect_with :rspec do |expectations|
-    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
-  end
-
-  config.mock_with :rspec do |mocks|
-    mocks.verify_partial_doubles = true
-  end
-
-  config.shared_context_metadata_behavior = :apply_to_host_groups
-end
-````
-
-## spec/opaque_id_spec.rb
-
-```ruby
-# frozen_string_literal: true
-
-require "spec_helper"
-
-RSpec.describe OpaqueId do
-  describe ".generate" do
-    it "generates IDs of default length" do
-      id = described_class.generate
-      expect(id.length).to eq(21)
-    end
-
-    it "generates IDs of custom length" do
-      id = described_class.generate(size: 32)
-      expect(id.length).to eq(32)
-    end
-
-    it "uses only characters from the alphabet" do
-      alphabet = "abc123"
-      id = described_class.generate(size: 100, alphabet: alphabet)
-      expect(id.chars.all? { |c| alphabet.include?(c) }).to be true
-    end
-
-    it "generates unique IDs" do
-      ids = 10_000.times.map { described_class.generate }
-      expect(ids.uniq.length).to eq(10_000)
-    end
-
-    it "raises error for invalid size" do
-      expect { described_class.generate(size: 0) }.to raise_error(OpaqueId::ConfigurationError)
-      expect { described_class.generate(size: -1) }.to raise_error(OpaqueId::ConfigurationError)
-    end
-
-    it "raises error for empty alphabet" do
-      expect { described_class.generate(alphabet: "") }.to raise_error(OpaqueId::ConfigurationError)
-    end
-
-    context "with 64-character alphabet" do
-      it "uses fast path" do
-        id = described_class.generate(size: 21, alphabet: OpaqueId::STANDARD_ALPHABET)
-        expect(id.length).to eq(21)
-        expect(id.chars.all? { |c| OpaqueId::STANDARD_ALPHABET.include?(c) }).to be true
-      end
-    end
-  end
-
-  describe "statistical uniformity" do
-    it "distributes characters evenly" do
-      alphabet = "0123456789"
-      samples = 10_000.times.map { described_class.generate(size: 1, alphabet: alphabet) }
-
-      frequency = samples.tally
-      expected = samples.length / alphabet.length
-
-      # Chi-square test: all frequencies should be within 20% of expected
-      frequency.each_value do |count|
-        deviation = (count - expected).abs.to_f / expected
-        expect(deviation).to be < 0.2
-      end
-    end
-  end
-end
-```

data/tasks/references/original_identifiable_concern_and_nanoid.md

@@ -1,110 +0,0 @@
-This is the original functionality we are replicating and enhancing. typically implemented as a concern in a Model via `include Identifiable`
-
-```ruby
-require "nanoid"
-
-# generate a public_id (nanoid) when creating new records
-# unique URL-friendly ID that'll prevent exposing incremental db ids where
-# we otherwise can't or don't want to use friendly_ids e.g. in URLs and APIs
-#
-# https://planetscale.com/blog/why-we-chose-nanoids-for-planetscales-api#generating-nanoids-in-rails
-# https://maful.web.id/posts/how-i-use-nano-id-in-rails/
-# https://zelark.github.io/nano-id-cc/
-module Identifiable
-  extend ActiveSupport::Concern
-
-  included do
-    before_create :set_public_id
-  end
-
-  PUBLIC_ID_ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz"
-  PUBLIC_ID_LENGTH = 18
-  MAX_RETRY = 1000
-
-  PUBLIC_ID_REGEX = /[#{PUBLIC_ID_ALPHABET}]{#{PUBLIC_ID_LENGTH}}\z/
-
-  class_methods do
-    def generate_nanoid(alphabet: PUBLIC_ID_ALPHABET, size: PUBLIC_ID_LENGTH)
-      Nanoid.generate(size:, alphabet:)
-    end
-  end
-
-  def set_public_id
-    return if public_id.present?
-
-    MAX_RETRY.times do
-      self.public_id = generate_public_id
-      return unless self.class.where(public_id:).exists?
-    end
-    raise "Failed to generate a unique public id after #{MAX_RETRY} attempts"
-  end
-
-  def generate_public_id
-    self.class.generate_nanoid(alphabet: PUBLIC_ID_ALPHABET)
-  end
-end
-```
-
-The original nanoid.rb is below
-
-```ruby
-require 'securerandom'
-
-module Nanoid
-  SAFE_ALPHABET = '_-0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'.freeze
-
-  def self.generate(size: 21, alphabet: SAFE_ALPHABET, non_secure: false)
-    return non_secure_generate(size: size, alphabet: alphabet) if non_secure
-
-    return simple_generate(size: size) if alphabet == SAFE_ALPHABET
-
-    complex_generate(size: size, alphabet: alphabet)
-  end
-
-  private
-
-  def self.simple_generate(size:)
-    bytes = random_bytes(size)
-
-    (0...size).reduce('') do |acc, i|
-      acc << SAFE_ALPHABET[bytes[i] & 63]
-    end
-  end
-
-  def self.complex_generate(size:, alphabet:)
-    alphabet_size = alphabet.size
-    mask = (2 << Math.log(alphabet_size - 1) / Math.log(2)) - 1
-    step = (1.6 * mask * size / alphabet_size).ceil
-
-    id = ''
-
-    loop do
-      bytes = random_bytes(size)
-      (0...step).each do |idx|
-        byte = bytes[idx] & mask
-        character = byte && alphabet[byte]
-        if character
-          id << character
-          return id if id.size == size
-        end
-      end
-    end
-  end
-
-  def self.non_secure_generate(size:, alphabet:)
-    alphabet_size = alphabet.size
-
-    id = ''
-
-    size.times do
-      id << alphabet[(Random.rand * alphabet_size).floor]
-    end
-
-    id
-  end
-
-  def self.random_bytes(size)
-    SecureRandom.random_bytes(size).bytes
-  end
-end
-```

data/tasks/tasks-0001-prd-opaque-id-gem.md

@@ -1,109 +0,0 @@
-# Task List: OpaqueId Ruby Gem Implementation
-
-Based on PRD: `0001-prd-opaque-id-gem.md`
-
-## Relevant Files
-
-- `lib/opaque_id.rb` - Main module with core ID generation functionality and error classes
-- `lib/opaque_id/version.rb` - Version constant (already exists)
-- `lib/opaque_id/model.rb` - ActiveRecord concern for model integration
-- `lib/generators/opaque_id/install_generator.rb` - Rails generator for migrations and model updates
-- `lib/generators/opaque_id/templates/migration.rb.tt` - Migration template for generator
-- `opaque_id.gemspec` - Gem specification and dependencies (updated for Rails 8.0+)
-- `Gemfile` - Development dependencies
-- `Rakefile` - Rake tasks for testing and linting
-- `.rubocop.yml` - RuboCop configuration for code quality
-- `test/test_helper.rb` - Test setup with Rails configuration and deprecation fixes
-- `test/test_opaque_id.rb` - Unit tests for main module
-- `test/opaque_id_test.rb` - Comprehensive tests for core functionality
-- `test/opaque_id/model_test.rb` - Unit tests for ActiveRecord concern
-- `test/opaque_id/generators/install_generator_test.rb` - Unit tests for generator
-- `README.md` - Documentation and usage examples
-- `CHANGELOG.md` - Version history and changes
-
-### Notes
-
-- Unit tests should be placed in the `test/` directory following Minitest conventions
-- Use `ruby -Ilib:test test/test_opaque_id.rb` to run specific test files
-- Use `rake test` to run all tests (once Rakefile is configured)
-- The existing `test/test_helper.rb` already sets up Minitest and loads the gem
-
-## Tasks
-
-- [x] 1.0 Implement Core ID Generation Module
-
-  - [x] 1.1 Create error classes (Error, GenerationError, ConfigurationError)
-  - [x] 1.2 Implement alphabet constants (STANDARD_ALPHABET, ALPHANUMERIC_ALPHABET)
-  - [x] 1.3 Implement generate_fast method for 64-character alphabets using bitwise operations
-  - [x] 1.4 Implement generate_unbiased method with rejection sampling algorithm
-  - [x] 1.5 Implement main generate method with parameter validation
-  - [x] 1.6 Add proper error handling for invalid size and empty alphabet
-  - [x] 1.7 Add require statements for SecureRandom and version
-
-- [x] 2.0 Create ActiveRecord Model Integration
-
-  - [x] 2.1 Create OpaqueId::Model concern with ActiveSupport::Concern
-  - [x] 2.2 Implement before_create callback for automatic ID generation
-  - [x] 2.3 Add find_by_opaque_id and find_by_opaque_id! class methods
-  - [x] 2.4 Implement collision detection with configurable retry attempts
-  - [x] 2.5 Add configuration options (column, length, alphabet, require_letter_start, purge_chars, max_retry)
-  - [x] 2.6 Implement set_opaque_id private method with collision handling
-  - [x] 2.7 Add generate_opaque_id private method using main module
-  - [x] 2.8 Handle edge cases (already has ID, collision resolution failure)
-
-- [x] 3.0 Build Rails Generator for Easy Setup
-
-  - [x] 3.1 Create lib/generators/opaque_id directory structure
-  - [x] 3.2 Implement InstallGenerator class with Rails::Generators::Base
-  - [x] 3.3 Add table_name argument and column_name option handling
-  - [x] 3.4 Create migration template (migration.rb.tt) with add_column and add_index
-  - [x] 3.5 Implement create_migration_file method with error handling
-  - [x] 3.6 Add model file modification to include OpaqueId::Model
-  - [x] 3.7 Handle edge cases (missing model file, already included, different class names)
-  - [x] 3.8 Add proper console output and error messages
-
-- [x] 4.0 Update Gem Configuration and Dependencies
-
-  - [x] 4.1 Update gemspec with proper summary and description
-  - [x] 4.2 Add ActiveRecord and ActiveSupport dependencies (>= 8.0)
-  - [x] 4.3 Add development dependencies (rake, sqlite3, rubocop, rails)
-  - [x] 4.4 Update metadata (homepage, source_code_uri, changelog_uri)
-  - [x] 4.5 Set required_ruby_version to >= 3.2
-  - [x] 4.6 Configure file inclusion and exclusion patterns
-  - [x] 4.7 Update Gemfile to match gemspec dependencies
-  - [x] 4.8 Update Rakefile with test and rubocop tasks
-
-- [x] 5.0 Create Comprehensive Test Suite
-
-  - [x] 5.1 Create test/opaque_id directory structure
-  - [x] 5.2 Implement test_opaque_id.rb with core module tests
-  - [x] 5.3 Add tests for generate method (default length, custom length, alphabet validation)
-  - [x] 5.4 Add tests for error conditions (invalid size, empty alphabet)
-  - [x] 5.5 Add statistical uniformity tests for character distribution
-  - [x] 5.6 Add performance benchmark tests for different alphabet sizes
-  - [x] 5.7 Create test/opaque_id/model_test.rb for ActiveRecord concern
-  - [x] 5.8 Test model integration (automatic generation, find methods, configuration)
-  - [x] 5.9 Test collision detection and retry logic
-  - [x] 5.10 Create test/opaque_id/generators/install_generator_test.rb
-  - [x] 5.11 Test generator behavior (migration creation, model modification, edge cases)
-  - [x] 5.12 Add test database setup and cleanup
-
-- [x] 5.13 Configure RuboCop for code quality
-
-  - [x] 5.13.1 Create .rubocop.yml configuration file
-  - [x] 5.13.2 Set appropriate rules for gem development
-  - [x] 5.13.3 Auto-correct all RuboCop offenses
-  - [x] 5.13.4 Fix Rails 8.1 deprecation warning in test helper
-
-- [ ] 6.0 Write Documentation and Examples
-  - [x] 6.1 Update README.md with comprehensive feature list
-  - [x] 6.2 Add installation instructions and gem usage
-  - [x] 6.3 Create basic usage examples with code snippets
-  - [x] 6.4 Add custom configuration examples
-  - [x] 6.5 Document standalone generation usage
-  - [x] 6.6 Add configuration options table with defaults
-  - [x] 6.7 Document alphabet options (ALPHANUMERIC_ALPHABET, STANDARD_ALPHABET)
-  - [x] 6.8 Add algorithm explanation and performance benchmarks
-  - [x] 6.9 Create security considerations and use case examples
-  - [x] 6.10 Add contributing guidelines and license information
-  - [x] 6.11 Update CHANGELOG.md with version history