opaque_id 1.4.0 → 1.7.0

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

data/tasks/tasks-0002-prd-publishing-release-automation.md

@@ -1,177 +0,0 @@
-# Task List: Publishing & Release Automation Implementation (Release Please Approach)
-
-## Summary
-
-Implement fully automated publishing and release system for OpaqueId gem using **Release Please** (Google's tool), **Bundler's release tasks**, and **RubyGems trusted publishing** with `rubygems/release-gem` action.
-
-## Completed Tasks
-
-- [x] 0.1 Create comprehensive PRD for publishing and release automation
-- [x] 0.2 Research Ruby ecosystem equivalents to Changesets
-- [x] 0.3 Define technical requirements and dependencies
-- [x] 0.4 Update approach to use Release Please (Google's tool)
-- [x] 0.5 Implement complete automated publishing and release system
-
-## Pending Tasks
-
-### Phase 1: Core Release Please Setup (Priority: High)
-
-#### 1.0 Set Up Release Please Configuration
-
-- [x] 1.1 Create `release-please-config.json` configuration file
-- [x] 1.2 Configure Release Please for Ruby gem with `release-type: ruby`
-- [x] 1.3 Set up conventional commits parsing for version bumping
-- [x] 1.4 Configure changelog generation from conventional commits
-- [x] 1.5 Test Release Please configuration with sample commits
-
-#### 2.0 Create Release Please Workflow
-
-- [x] 2.1 Create `.github/workflows/release-please.yml` workflow
-- [x] 2.2 Configure workflow to run on push to main branch
-- [x] 2.3 Set up permissions for creating/updating release PRs
-- [x] 2.4 Configure workflow to use `googleapis/release-please-action@v4`
-- [x] 2.5 Test workflow with sample conventional commits
-
-#### 3.0 Set Up RubyGems Trusted Publishing
-
-- [ ] 3.1 Configure trusted publishing on RubyGems.org (UI step) - **MANUAL STEP REQUIRED**
-- [x] 3.2 Create `.github/workflows/publish.yml` workflow
-- [x] 3.3 Configure workflow to trigger on GitHub Release published
-- [x] 3.4 Set up OIDC permissions (`id-token: write`, `contents: write`)
-- [x] 3.5 Configure `rubygems/release-gem@v1` action for publishing
-
-### Phase 2: Quality Gates & Security (Priority: High)
-
-#### 4.0 Implement Quality Gates
-
-- [x] 4.1 Add test execution to release-please workflow (via enhanced main.yml)
-- [x] 4.2 Add RuboCop execution to release-please workflow (via enhanced main.yml)
-- [x] 4.3 Add bundle audit for security scanning (via enhanced main.yml)
-- [x] 4.4 Configure workflow to fail on quality gate failures
-- [x] 4.5 Test quality gates with intentional failures
-
-#### 5.0 Configure Dependabot
-
-- [x] 5.1 Create `.github/dependabot.yml` configuration file
-- [x] 5.2 Configure weekly dependency updates (Monday 9 AM)
-- [x] 5.3 Set up security update prioritization
-- [x] 5.4 Configure update strategy and labels
-- [x] 5.5 Test dependabot with sample dependency updates
-
-### Phase 3: Documentation & Testing (Priority: Medium)
-
-#### 6.0 Documentation and Testing
-
-- [x] 6.1 Document the complete Release Please workflow (in PRD and task files)
-- [x] 6.2 Create troubleshooting guide for release failures (in PRD)
-- [x] 6.3 Test complete release workflow end-to-end (local testing completed)
-- [x] 6.4 Create release process checklist (in PRD)
-- [x] 6.5 Update README with release automation information (comprehensive documentation)
-
-#### 7.0 Monitoring and Maintenance
-
-- [x] 7.1 Set up release monitoring and alerts (via GitHub Actions)
-- [ ] 7.2 Create release metrics dashboard (optional - not needed for MVP)
-- [x] 7.3 Implement release health checks (via CI workflows)
-- [x] 7.4 Set up automated dependency security scanning (via Dependabot and bundle-audit)
-- [x] 7.5 Create maintenance procedures for release system (documented in PRD)
-
-## Technical Dependencies
-
-### Required Tools
-
-- **Release Please**: Google's tool for PR-based versioning and changelog generation
-- **Bundler's release tasks**: Built-in rake tasks (already present from `bundle gem`)
-- **bundle-audit**: Security scanning
-- **rubygems/release-gem**: GitHub Action for RubyGems publishing
-
-### Configuration Files
-
-- `release-please-config.json`: Release Please configuration
-- `.github/dependabot.yml`: Dependency update configuration
-- `.github/workflows/release-please.yml`: Release PR workflow
-- `.github/workflows/publish.yml`: Publishing workflow
-
-### RubyGems Configuration
-
-- Trusted publishing setup on RubyGems.org
-- GitHub OIDC configuration
-- MFA requirement enforcement
-
-## Workflow Overview
-
-### Release Please Workflow (release-please.yml)
-
-```yaml
-name: release-please
-on:
-  push:
-    branches: [main]
-permissions:
-  contents: write
-  pull-requests: write
-jobs:
-  release:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: googleapis/release-please-action@v4
-        with:
-          release-type: ruby
-```
-
-### Publishing Workflow (publish.yml)
-
-```yaml
-name: publish-gem
-on:
-  release:
-    types: [published]
-permissions:
-  id-token: write
-  contents: write
-jobs:
-  push:
-    name: Push gem to RubyGems.org
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          persist-credentials: false
-      - uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: ruby
-          bundler-cache: true
-      - uses: rubygems/release-gem@v1
-```
-
-## Success Criteria
-
-- [x] Release Please creates release PRs automatically from conventional commits
-- [x] Version file (`lib/opaque_id/version.rb`) is automatically updated
-- [x] Changelog is automatically generated from conventional commits
-- [x] Merging release PR creates GitHub Release and publishes to RubyGems.org
-- [x] All quality gates pass before release
-- [x] Dependencies are automatically updated weekly
-- [x] No manual intervention required for releases (except RubyGems trusted publishing setup)
-- [x] RubyGems trusted publishing works without API keys
-
-## Relevant Files
-
-- `release-please-config.json` - Release Please configuration
-- `.github/workflows/release-please.yml` - Release PR workflow
-- `.github/workflows/publish.yml` - Publishing workflow
-- `.github/dependabot.yml` - Dependency update configuration
-- `lib/opaque_id/version.rb` - Version file for automatic updates
-- `CHANGELOG.md` - Auto-generated changelog
-- `opaque_id.gemspec` - Gem specification
-- `Rakefile` - Rake tasks for building and releasing
-
-## Notes
-
-- This approach uses the widely-adopted Ruby ecosystem standard
-- Release Please provides the same ergonomics as Changesets
-- Uses RubyGems trusted publishing for enhanced security
-- Fully automated process with PR-based releases
-- Based on conventional commits specification
-- Compatible with existing gem structure and dependencies
-- No need for commitlint or pre-commit hooks (Release Please handles conventional commits)

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

@@ -1,84 +0,0 @@
-# Task List: OpaqueId Documentation Site
-
-## Relevant Files
-
-- `docs/_config.yml` - Jekyll configuration file for the documentation site
-- `docs/Gemfile` - Ruby dependencies for Jekyll and Just the Docs theme
-- `docs/index.md` - Homepage of the documentation site
-- `docs/getting-started.md` - Quick start guide for developers
-- `docs/installation.md` - Detailed installation instructions
-- `docs/usage.md` - Usage examples and integration guides
-- `docs/configuration.md` - Configuration options and examples
-- `docs/alphabets.md` - Built-in alphabets and custom alphabet guide
-- `docs/algorithms.md` - Technical details about algorithms
-- `docs/performance.md` - Performance benchmarks and optimization
-- `docs/security.md` - Security considerations and best practices
-- `docs/use-cases.md` - Real-world examples and applications
-- `docs/development.md` - Contributing guidelines and development setup
-- `docs/api-reference.md` - Complete API documentation
-- `docs/assets/images/` - Directory for documentation images and assets
-- `.github/workflows/docs.yml` - GitHub Actions workflow for documentation deployment
-- `README.md` - Source content for documentation migration
-
-### Notes
-
-- The documentation site will be completely separate from the main gem codebase
-- Jekyll uses Markdown files with YAML front matter for page configuration
-- GitHub Pages will automatically build and deploy the Jekyll site
-- All content will be manually migrated from the existing README.md
-
-## Tasks
-
-- [x] 1.0 Set up Jekyll site structure and configuration
-
-  - [x] 1.1 Create `/docs` directory structure
-  - [x] 1.2 Initialize Jekyll site with `jekyll new docs --force`
-  - [x] 1.3 Configure `_config.yml` for Just the Docs theme and GitHub Pages
-  - [x] 1.4 Set up `Gemfile` with just-the-docs gem and GitHub Pages plugins
-  - [x] 1.5 Configure site metadata (title, description, author, URL)
-  - [x] 1.6 Set up proper permalinks and URL structure
-  - [x] 1.7 Configure search functionality and navigation settings
-
-- [x] 2.0 Create GitHub Actions workflow for documentation deployment
-
-  - [x] 2.1 Create `.github/workflows/docs.yml` workflow file
-  - [x] 2.2 Configure workflow to trigger on pushes to main branch
-  - [x] 2.3 Set up Jekyll build process with proper Ruby version
-  - [x] 2.4 Configure GitHub Pages deployment with proper permissions
-  - [x] 2.5 Add error handling and build status notifications
-  - [x] 2.6 Test workflow with initial deployment
-
-- [x] 3.0 Migrate and organize content from README into documentation pages
-
-  - [x] 3.1 Create homepage (`index.md`) with overview, badges, and introduction
-  - [x] 3.2 Extract and create getting-started.md with quick start guide
-  - [x] 3.3 Migrate installation content to installation.md with all methods
-  - [x] 3.4 Create usage.md with standalone and ActiveRecord examples
-  - [x] 3.5 Extract configuration options to configuration.md with examples
-  - [x] 3.6 Create alphabets.md with built-in alphabets and custom guide
-  - [x] 3.7 Migrate algorithm details to algorithms.md with technical explanations
-  - [x] 3.8 Create performance.md with benchmarks and optimization tips
-  - [x] 3.9 Extract security content to security.md with best practices
-  - [x] 3.10 Create use-cases.md with real-world examples and applications
-  - [x] 3.11 Migrate development content to development.md with setup instructions
-  - [x] 3.12 Create api-reference.md with complete method documentation
-
-- [x] 4.0 Implement navigation structure and cross-references
-
-  - [x] 4.1 Configure navigation in `_config.yml` with proper page ordering
-  - [x] 4.2 Add proper YAML front matter to all pages with titles and descriptions
-  - [x] 4.3 Create cross-references between related pages using markdown links
-  - [x] 4.4 Add table of contents to longer pages using Just the Docs features
-  - [x] 4.5 Implement proper heading hierarchy for consistent navigation
-  - [x] 4.6 Add breadcrumb navigation where appropriate
-  - [x] 4.7 Test navigation flow and ensure all links work correctly
-
-- [x] 5.0 Configure Just the Docs theme and optimize for GitHub Pages
-  - [x] 5.1 Customize theme colors and branding to match OpaqueId
-  - [x] 5.2 Configure code syntax highlighting for Ruby examples
-  - [x] 5.3 Set up responsive design and mobile optimization
-  - [x] 5.4 Add SEO meta tags and Open Graph properties
-  - [x] 5.5 Configure sitemap and RSS feed generation
-  - [x] 5.6 Optimize page loading speed and performance
-  - [x] 5.7 Test site functionality across different browsers and devices
-  - [x] 5.8 Validate HTML and accessibility compliance