opaque_id 1.4.0 → 1.7.0

data/tasks/0003-prd-documentation-site.md

@@ -1,191 +0,0 @@
-# Product Requirements Document: OpaqueId Documentation Site
-
-## Introduction/Overview
-
-Create a professional documentation website for the OpaqueId Ruby gem using [Just the Docs](https://just-the-docs.com) Jekyll theme. The site will provide comprehensive, developer-focused documentation that mirrors the README content but with improved navigation, search capabilities, and a clean, minimal design similar to the Just the Docs site itself.
-
-**Problem Solved:** The current README is comprehensive but long (1600+ lines), making it difficult to navigate and find specific information quickly. A dedicated documentation site will improve developer experience and make the gem more accessible.
-
-**Goal:** Create a professional, searchable documentation site that makes OpaqueId easy to understand and implement for developers.
-
-## Goals
-
-1. **Improve Developer Experience**: Provide easy navigation and search for finding specific documentation
-2. **Professional Presentation**: Create a polished, modern documentation site that reflects the quality of the gem
-3. **Maintain Content Quality**: Preserve all valuable information from the README while improving organization
-4. **Enable Auto-Deployment**: Set up GitHub Actions for automatic deployment on successful pushes
-5. **Ensure Accessibility**: Make documentation accessible and mobile-friendly
-6. **Minimize Maintenance**: Keep the site simple and maintainable
-
-## User Stories
-
-- **As a developer** evaluating OpaqueId, I want to quickly understand what the gem does and how to install it
-- **As a developer** implementing OpaqueId, I want to find specific configuration options and usage examples
-- **As a developer** troubleshooting issues, I want to search for specific error messages or solutions
-- **As a developer** learning advanced features, I want to explore performance benchmarks and security considerations
-- **As a developer** contributing to the project, I want to understand the development setup and guidelines
-
-## Functional Requirements
-
-### 1. Site Structure & Navigation
-
-1.1. Create a `/docs` directory with Jekyll site structure
-1.2. Implement sidebar navigation based on README Table of Contents
-1.3. Use minimal, flat navigation structure (no collapsible sections)
-1.4. Include search functionality using Just the Docs built-in search
-1.5. Add "Getting Started" quick start guide as a separate page
-
-### 2. Content Organization
-
-2.1. Convert README sections into individual documentation pages
-2.2. Create logical page hierarchy: Home → Getting Started → Installation → Usage → Configuration → etc.
-2.3. Maintain all existing content from README
-2.4. Add code syntax highlighting for Ruby examples
-2.5. Include proper cross-references between pages
-
-### 3. Design & Styling
-
-3.1. Use Just the Docs theme with default light/dark mode switching
-3.2. Apply minimal design similar to just-the-docs.com
-3.3. Include OpaqueId branding and gem badges
-3.4. Ensure responsive design for mobile devices
-3.5. Use consistent typography and spacing
-
-### 4. GitHub Pages Integration
-
-4.1. Configure site for `https://nyaggah.github.io/opaque_id`
-4.2. Set up GitHub Actions workflow for automatic deployment
-4.3. Deploy on successful pushes to main branch
-4.4. Include proper Jekyll configuration for GitHub Pages
-
-### 5. Content Pages
-
-5.1. **Home**: Overview, badges, quick introduction
-5.2. **Getting Started**: Step-by-step installation and basic usage
-5.3. **Installation**: Detailed installation instructions and requirements
-5.4. **Usage**: Standalone and ActiveRecord integration examples
-5.5. **Configuration**: All configuration options and examples
-5.6. **Alphabets**: Built-in alphabets and custom alphabet guide
-5.7. **Algorithms**: Technical details about fast path and unbiased algorithms
-5.8. **Performance**: Benchmarks and optimization tips
-5.9. **Security**: Security considerations and best practices
-5.10. **Use Cases**: Real-world examples and applications
-5.11. **Development**: Contributing guidelines and development setup
-5.12. **API Reference**: Complete method documentation
-
-### 6. Technical Implementation
-
-6.1. Use Jekyll with Just the Docs theme
-6.2. Configure `_config.yml` for GitHub Pages
-6.3. Set up proper front matter for all pages
-6.4. Include necessary Jekyll plugins for GitHub Pages
-6.5. Optimize for fast loading and SEO
-
-## Non-Goals (Out of Scope)
-
-- **Live Code Examples**: No interactive demos or live code execution
-- **Version-Specific Documentation**: Single version documentation only
-- **Automatic README Sync**: Manual content maintenance
-- **Custom Domain**: Using default GitHub.io domain
-- **Breadcrumb Navigation**: Sidebar navigation only
-- **User Authentication**: Public documentation only
-- **Comments/Feedback System**: Static documentation only
-
-## Design Considerations
-
-### Visual Design
-
-- **Theme**: [Just the Docs](https://just-the-docs.com) Jekyll theme
-- **Color Scheme**: Default light/dark mode switching
-- **Layout**: Clean, minimal design with focus on content
-- **Typography**: Clear, readable fonts with proper hierarchy
-- **Navigation**: Left sidebar with flat structure
-
-### Content Structure
-
-- **Homepage**: Hero section with badges, overview, and quick start
-- **Sidebar**: Logical grouping of documentation sections
-- **Search**: Full-text search across all documentation
-- **Code Examples**: Syntax-highlighted Ruby code blocks
-- **Cross-References**: Links between related sections
-
-## Technical Considerations
-
-### Jekyll Configuration
-
-- Use gem-based approach with `just-the-docs` gem
-- Configure for GitHub Pages compatibility
-- Include necessary plugins: jekyll-feed, jekyll-sitemap, jekyll-seo-tag
-- Set up proper permalinks and URL structure
-
-### GitHub Actions Workflow
-
-- Trigger on pushes to main branch
-- Build Jekyll site
-- Deploy to GitHub Pages
-- Include proper error handling and notifications
-
-### File Structure
-
-```
-/docs/
-├── _config.yml
-├── Gemfile
-├── index.md (Home)
-├── getting-started.md
-├── installation.md
-├── usage.md
-├── configuration.md
-├── alphabets.md
-├── algorithms.md
-├── performance.md
-├── security.md
-├── use-cases.md
-├── development.md
-├── api-reference.md
-└── assets/
-    └── images/
-```
-
-## Success Metrics
-
-1. **Developer Adoption**: Increased gem downloads and usage
-2. **User Engagement**: Time spent on documentation pages
-3. **Search Usage**: Frequency of search functionality usage
-4. **Page Performance**: Fast loading times (< 3 seconds)
-5. **Mobile Usage**: Successful mobile documentation access
-6. **SEO Performance**: High search engine rankings for OpaqueId-related queries
-
-## Open Questions
-
-1. Should we include a changelog page or link to GitHub releases?
-2. Do we want to include a "Troubleshooting" section for common issues?
-3. Should we add a "Migration Guide" for users switching from nanoid.rb?
-4. Do we want to include performance comparison charts or keep them as tables?
-5. Should we add a "Community" section with links to discussions and support?
-
-## Implementation Priority
-
-### Phase 1: Core Setup
-
-- Set up Jekyll site structure
-- Configure GitHub Pages deployment
-- Create basic page structure
-
-### Phase 2: Content Migration
-
-- Convert README content to individual pages
-- Set up navigation and cross-references
-- Add code syntax highlighting
-
-### Phase 3: Enhancement
-
-- Add search functionality
-- Optimize performance and SEO
-- Polish design and user experience
-
-### Phase 4: Launch
-
-- Deploy to GitHub Pages
-- Test all functionality
-- Announce to community

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
-```