opaque_id 1.1.0

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

@@ -0,0 +1,206 @@
+# Product Requirements Document: Publishing & Release Automation
+
+## Introduction/Overview
+
+This PRD outlines the implementation of a fully automated publishing and release system for the OpaqueId Ruby gem. The system will automatically version, test, and publish releases to RubyGems.org based on conventional commits, eliminating manual release processes and ensuring consistent, professional releases.
+
+**Problem**: Manual release processes are error-prone, time-consuming, and inconsistent. Without automated versioning and publishing, releases can be delayed, version numbers can be inconsistent, and changelogs can be incomplete.
+
+**Goal**: Implement a fully automated CI/CD pipeline that handles versioning, testing, changelog generation, and publishing based on conventional commits and the state of the main branch.
+
+## Goals
+
+1. **Automated Versioning**: Automatically determine version bumps (patch/minor/major) based on conventional commit types
+2. **Automated Publishing**: Automatically publish to RubyGems.org when changes are ready
+3. **Quality Gates**: Ensure all tests pass, code quality standards are met, and security checks pass before release
+4. **Automated Changelog**: Generate changelog entries from conventional commits
+5. **Dependency Management**: Automatically check for and update dependencies weekly
+6. **Commit Standardization**: Enforce conventional commit format for consistent messaging
+7. **Security**: Use RubyGems trusted publishing for secure, keyless releases
+
+## User Stories
+
+### As a Developer
+
+- **US1**: I want my commits to automatically trigger appropriate version bumps so that I don't have to manually manage version numbers
+- **US2**: I want releases to be published automatically when I push to main so that I don't have to remember to manually publish
+- **US3**: I want commit message validation so that I follow consistent formatting standards
+- **US4**: I want automated dependency updates so that my gem stays secure and up-to-date
+
+### As a Maintainer
+
+- **US5**: I want automated testing and quality checks before release so that I can trust the published code
+- **US6**: I want automated changelog generation so that users know what changed in each release
+- **US7**: I want security scanning before release so that vulnerabilities are caught early
+
+### As a User
+
+- **US8**: I want consistent, predictable releases so that I can trust the gem's stability
+- **US9**: I want clear changelogs so that I understand what changed between versions
+
+## Functional Requirements
+
+### 1. Conventional Commits Integration
+
+1.1. **Commit Message Validation**: Enforce conventional commit format (feat:, fix:, docs:, etc.) on all commits
+1.2. **Commit Linting**: Use commitlint or similar tool to validate commit message format
+1.3. **Pre-commit Hooks**: Automatically validate commit messages before they are accepted
+1.4. **Commit Types**: Support standard types: feat, fix, docs, style, refactor, perf, test, chore, ci, build
+
+### 2. Automated Versioning
+
+2.1. **Semantic Versioning**: Use semantic versioning (MAJOR.MINOR.PATCH) based on conventional commits
+2.2. **Version Bump Logic**:
+
+- `feat:` commits → MINOR version bump
+- `fix:` commits → PATCH version bump
+- `BREAKING CHANGE:` or `!` → MAJOR version bump
+- Other types → no version bump
+  2.3. **Version Detection**: Automatically detect when version should be bumped based on unreleased commits
+  2.4. **Version File Update**: Automatically update `lib/opaque_id/version.rb` with new version
+
+### 3. GitHub Actions Workflow
+
+3.1. **Single Workflow**: Update existing `main.yml` to include release automation
+3.2. **Trigger Conditions**: Run on push to main branch when unreleased changes exist
+3.3. **Workflow Steps**:
+
+- Checkout code
+- Setup Ruby environment
+- Install dependencies
+- Run tests
+- Run RuboCop
+- Security audit
+- Determine version bump
+- Update version file
+- Generate changelog
+- Create git tag
+- Publish to RubyGems.org
+- Create GitHub release
+
+### 4. Quality Gates
+
+4.1. **Test Execution**: Run full test suite before any release
+4.2. **Code Quality**: Run RuboCop and fail if violations exist
+4.3. **Security Scanning**: Run `bundle audit` to check for vulnerable dependencies
+4.4. **Dependency Check**: Ensure all dependencies are up-to-date and secure
+
+### 5. Changelog Generation
+
+5.1. **Automated Generation**: Generate changelog from conventional commits since last release
+5.2. **Changelog Format**: Use conventional changelog format with categorized sections
+5.3. **Changelog Sections**: Features, Bug Fixes, Breaking Changes, Documentation, etc.
+5.4. **Changelog Update**: Automatically update `CHANGELOG.md` with new entries
+
+### 6. RubyGems Publishing
+
+6.1. **Trusted Publishing**: Use RubyGems trusted publishing (no API keys required)
+6.2. **MFA Enforcement**: Ensure MFA is required for publishing (already configured)
+6.3. **Build Process**: Build gem package before publishing
+6.4. **Publish Process**: Automatically push to RubyGems.org when all checks pass
+
+### 7. Dependabot Integration
+
+7.1. **Weekly Updates**: Check for dependency updates every Monday at 9 AM
+7.2. **Update Types**: Check for both direct and indirect dependency updates
+7.3. **Security Updates**: Prioritize security-related updates
+7.4. **Update Strategy**: Create pull requests for dependency updates
+
+### 8. Git Tag Management
+
+8.1. **Automatic Tagging**: Create git tags for each release (e.g., `v1.2.3`)
+8.2. **Tag Format**: Use semantic versioning format with `v` prefix
+8.3. **Tag Push**: Automatically push tags to GitHub repository
+8.4. **GitHub Release**: Create GitHub release with changelog and tag
+
+## Non-Goals (Out of Scope)
+
+1. **Manual Release Override**: No manual release triggers or overrides
+2. **Multiple Branch Support**: Only support releases from main branch
+3. **Pre-release Versions**: No support for alpha/beta/rc versions initially
+4. **Monorepo Support**: Single gem repository only
+5. **Custom Versioning Logic**: No custom versioning rules beyond conventional commits
+6. **Rollback Automation**: No automatic rollback of failed releases
+
+## Technical Considerations
+
+### Dependencies
+
+- **Release Please**: Google's tool for PR-based versioning and changelog generation
+- **Bundler's release tasks**: Built-in rake tasks for building and tagging (already present)
+- **commitlint**: For commit message validation (optional)
+- **bundle-audit**: For security scanning
+
+### GitHub Actions
+
+- **googleapis/release-please-action**: For creating release PRs and versioning
+- **rubygems/release-gem**: For RubyGems publishing with trusted publishing
+- **actions/checkout**: For code checkout
+- **ruby/setup-ruby**: For Ruby environment setup
+
+### Configuration Files
+
+- **release-please-config.json**: Release Please configuration
+- **dependabot.yml**: Dependency update configuration
+- **.github/workflows/release-please.yml**: Release PR workflow
+- **.github/workflows/publish.yml**: Publishing workflow
+
+### RubyGems Trusted Publishing
+
+- Configure trusted publishing on RubyGems.org
+- Use GitHub OIDC for authentication
+- No API keys or secrets required
+
+## Success Metrics
+
+1. **Release Automation**: 100% of releases are automated (no manual intervention)
+2. **Release Frequency**: Ability to release multiple times per day if needed
+3. **Quality Gates**: 0% of releases with failing tests or security issues
+4. **Commit Compliance**: 100% of commits follow conventional commit format
+5. **Dependency Currency**: Dependencies updated within 7 days of availability
+6. **Release Time**: From commit to published gem in under 10 minutes
+
+## Open Questions
+
+1. **Commit Message Enforcement**: Should we use pre-commit hooks or GitHub Actions validation?
+2. **Changelog Format**: Should we use conventional-changelog or custom format?
+3. **Version Bump Strategy**: Should we batch multiple commits into single releases?
+4. **Rollback Strategy**: How should we handle failed releases or rollbacks?
+5. **Notification Strategy**: Should we notify maintainers of successful/failed releases?
+6. **Branch Protection**: Should we require status checks before merging to main?
+
+## Implementation Priority
+
+### Phase 1: Core Automation
+
+- Conventional commits validation
+- Automated versioning
+- Basic GitHub Actions workflow
+- RubyGems publishing
+
+### Phase 2: Quality & Security
+
+- Quality gates (tests, RuboCop, security)
+- Automated changelog generation
+- Dependabot integration
+
+### Phase 3: Polish & Monitoring
+
+- Enhanced notifications
+- Release monitoring
+- Performance optimization
+
+## Acceptance Criteria
+
+- [ ] All commits follow conventional commit format
+- [ ] Version numbers are automatically bumped based on commit types
+- [ ] Releases are automatically published to RubyGems.org
+- [ ] Changelog is automatically generated from commits
+- [ ] All tests pass before release
+- [ ] RuboCop passes before release
+- [ ] Security audit passes before release
+- [ ] Dependencies are automatically updated weekly
+- [ ] Git tags are automatically created for releases
+- [ ] GitHub releases are automatically created
+- [ ] RubyGems trusted publishing is configured
+- [ ] No manual intervention required for releases

data/tasks/references/opaque_gem_requirements.md

@@ -0,0 +1,482 @@
+# 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
+```