vial 0.0.0 → 0.2026.1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b37575d4301362c15f474046030d04e71fdf4a78ce6da1d5e10f9c14d25333a
-  data.tar.gz: a643a19d4c75049bf1b36ab7b078fb7c6ffa2c9a3028c0d67f3ed4d8f4414586
+  metadata.gz: f026c068653b089c9e389a48269f61b166df03350c2c483644d01d20449d75ac
+  data.tar.gz: ba3eb55ff916a330b79a7e23a33c64664384ac4b4c53bd9b3ca8c2cff48ddf01
 SHA512:
-  metadata.gz: 185493864794e252304dfb5aaf4aa9ce7d57b7d46ed7f2c5a6f60f2c95bf891cc7b335fac21801448ea2fd339075b43cdf86858aa93df9f8618149dfd98e0fe9
-  data.tar.gz: e9b49107485759a879c451dff0f6292dfbde946b3471daafd1f853d80b0f43d370a61472eb6e27bf28277ed12fa4186867c20a39db88588d978907ab1ed76825
+  metadata.gz: eb253aae25c559b82e53fce01af43eec1b378062b7d88163fb9967e3856bc35c4636213c8f08143e0f3baca7840f5d5c5df2d441f6e4cbd4cb3f537ed05496f8
+  data.tar.gz: 6c05034b6d5b9d9e39de6f61b59cd4e9e00d0b1acc88f36dc222ce7903a23a4728baa80813ca37b22b85d2eb9153f5ae2d42a638c516d81d507852af5c34abac

data/README.md

@@ -1,27 +1,318 @@
 # Vial: Fixtures, Reinvented
 
-Vial revolutionizes test fixtures with intelligent data management, dynamic generation, and seamless integration. Create maintainable test data with smart relationships, factories, and scenarios.
+Vial is a Ruby gem for Rails 8.1+ on Ruby 4.0+ that compiles programmable fixture intent into explicit, deterministic fixture files.
+
+## Requirements
+
+- Ruby 4.0+ (Ruby Box optional via `RUBY_BOX=1`)
+- Rails 8.1+
+
+## Support Policy
+
+- Ruby 4.0+ only
+- Rails 8.1+ only
+- No backward compatibility guarantees for older Ruby/Rails
+
+## Features
+
+- **Vial Compiler**: Ruby DSL input → explicit YAML fixtures output
+- **Fixture Discovery**: Automatically finds all YAML fixtures across configured paths
+- **Model Mapping Analysis**: Determines which models fixtures belong to using Rails conventions
+- **Validation**: Identifies orphaned fixtures that don't have corresponding models
+- **Multiple Detection Methods**: Supports all Rails fixture-to-model mapping methods
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add this gem to your Gemfile in the development/test group:
+
+```ruby
+group :development, :test do
+  gem 'vial'
+end
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Compile Vial Sources
+
+Vial reads `*.vial.rb` files from `test/vials` and writes YAML fixtures to `test/fixtures`:
+
+```bash
+bin/rails vial:compile
+```
+
+If `RUBY_BOX=1` is set, Vial evaluates vial sources inside Ruby::Box for isolation.
+
+Compile only specific vials:
+
+```bash
+bin/rails vial:compile:only[users,posts]
+```
+
+Note: `vial:compile:only` still validates the full dataset to catch global ID collisions; it only limits which files are written.
+
+Dry run (validate and show output targets without writing files):
+
+```bash
+bin/rails vial:compile:dry_run
+```
+
+Example `test/vials/users.vial.rb`:
+
+```ruby
+vial :users do
+  base do
+    active true
+    country "MA"
+  end
+
+  variant :admin do
+    role "admin"
+  end
+
+  variant :guest do
+    role "guest"
+    active false
+  end
+
+  sequence(:email) { |i| "user#{i}@test.local" }
+
+  generate 10, :admin
+  generate 50, :guest
+end
+```
+
+Output: `test/fixtures/users.yml` with deterministic IDs and explicit records.
+
+### Global Validation
+
+`vial:compile` validates the entire dataset before writing any fixtures. Any collision or duplicate label fails the compile with a precise error.
+
+### Composition
+
+```ruby
+vial :base_users, abstract: true do
+  base do
+    active true
+    country "MA"
+  end
+end
+
+vial :admin_users do
+  include_vial :base_users do
+    override :role, "admin"
+  end
+
+  generate 2
+end
+```
+
+`include_vial` composes base attributes (and sequences) only; variants are not imported.
+Abstract Vials are compile-time only and do not emit fixture files.
+
+### ID Strategy
+
+Derived IDs are deterministic integers based on the identity tuple:
+
+```
+[vial_name, record_type, label, variants[], index]
+```
+
+You can set a namespace range per Vial:
 
 ```ruby
-gem 'vial'
+vial :users, id_base: 100_000, id_range: 90_000 do
+  base do
+    role "user"
+  end
+
+  generate 3
+end
 ```
 
-And then execute:
+Explicit IDs are supported and never rewritten:
+
+```ruby
+vial :users do
+  base do
+    id 1001
+    role "system"
+  end
 
-    $ bundle install
+  generate 1
+end
+```
+
+Explain a derived ID:
+
+```bash
+bin/rails vial:explain_id['users.admin.eu[3]']
+```
 
-Or install it yourself as:
+### Determinism & Faker
 
-    $ gem install vial
+Vial seeds Ruby's RNG with `Vial.config.seed` (default: 1). As long as you avoid non-deterministic sources
+(`Time.now`, `SecureRandom`, etc.), recompiles produce identical output.
+
+If you use Faker, seed it explicitly:
+
+```ruby
+Faker::Config.random = Random.new(Vial.config.seed)
+```
+
+### Troubleshooting
+
+- `Vial: no vial definitions found` → No `*.vial.rb` files were found under `Vial.config.source_paths`.
+- `Vial: no records generated` → All vials are abstract or missing `generate` calls.
+- Fixture ID standardization skipped for ERB → ERB fixtures are not rewritten to avoid altering dynamic content.
+- Output path looks wrong → `Vial.config.output_path` defaults to the first `ActiveSupport::TestCase.fixture_paths` entry.
+
+### Configuration
+
+```ruby
+Vial.configure do |config|
+  config.source_paths = [Rails.root.join("test/vials")]
+  config.output_path = Rails.root.join("test/fixtures")
+  config.seed = 1
+end
+```
+
+Example Vial sources live in `examples/`:
+- `examples/users.vial.rb`
+- `examples/company__users.vial.rb`
+- `examples/base_users.vial.rb`
+- `examples/admin_users.vial.rb`
+
+Use `erb("...")` inside a Vial file to emit raw ERB (for associations or special IDs).
+
+Vial provides several rake tasks for fixture analysis:
+
+### Count Fixtures
+
+Get an overview of all YAML fixtures in your project:
+
+```bash
+bin/rails vial:count_fixtures
+```
+
+This shows:
+- Total number of fixture files
+- Distribution by directory
+- Configured fixture paths
+
+Note: `Vial.config.output_path` defaults to the first configured `fixture_paths` when available.
+
+### Clean Stale Vial Fixtures
+
+Remove fixture files previously generated by Vial that no longer have a matching vial definition:
+
+```bash
+bin/rails vial:clean
+```
+
+Vial tracks generated fixture files in `test/fixtures/.vial_manifest.yml` and only removes files listed there.
+
+### Analyze Fixtures
+
+Get detailed fixture-to-model mapping information:
+
+```bash
+bin/rails vial:analyze_fixtures
+```
+
+This shows:
+- Mapped fixtures with their corresponding models
+- Detection method used (fixture directive, set_fixture_class, or path inference)
+- Unmapped fixtures that may need attention
+- Any errors encountered during analysis
+
+### Validate Fixtures
+
+Check for orphaned fixtures without models:
+
+```bash
+bin/rails vial:validate_fixtures
+```
+
+This task:
+- Returns success (exit 0) if all fixtures are mapped
+- Returns failure (exit 1) if unmapped fixtures are found
+- Provides suggestions for fixing unmapped fixtures
+
+### Analyze Fixture IDs
+
+Check if fixtures use proper `ActiveRecord::FixtureSet.identify`:
+
+```bash
+bin/rails vial:analyze_fixture_ids
+```
+
+This shows:
+- Primary key type distribution (UUID, integer, string, etc.)
+- Fixtures that need ID standardization
+- Current vs expected ID values
+
+### Standardize Fixture IDs
+
+Convert hardcoded IDs to use `ActiveRecord::FixtureSet.identify`:
+
+```bash
+# Preview changes without applying
+bin/rails vial:standardize_fixture_ids:dry_run
+
+# Apply changes (with confirmation prompt)
+bin/rails vial:standardize_fixture_ids
+```
+
+This will:
+- Replace hardcoded integer IDs with `<%= ActiveRecord::FixtureSet.identify(:label) %>`
+- Replace hardcoded UUIDs with `<%= ActiveRecord::FixtureSet.identify(:label, :uuid) %>`
+- Skip string primary keys (often manually managed like slugs)
+- Ensure consistent, deterministic IDs across all fixtures
+
+## How Fixture Detection Works
+
+Vial uses three methods to determine which model a fixture belongs to:
+
+1. **_fixture Directive**: Checks for `_fixture: model_class:` in YAML files
+2. **set_fixture_class**: Uses mappings from `ActiveSupport::TestCase.set_fixture_class`
+3. **Path Inference**: Infers models from fixture paths using Rails naming conventions
+
+## Example Output
+
+```
+=== Vial Fixture Analysis ===
+
+Total fixtures found: 114
+Mapped to models: 93
+Unmapped fixtures: 21
+
+=== Mapped Fixtures ===
+platform/countries:
+  Model: Platform::Country
+  Table: platform_countries
+  Detection: path_inference
+
+active_llm_llms:
+  Model: ActiveLLM::LLM
+  Table: active_llm_llms
+  Detection: set_fixture_class
+```
 
-## Note
+## Contributing
 
-This is a placeholder gem. The full implementation is coming soon.
+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
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/examples/admin_users.vial.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+vial :admin_users do
+  include_vial :base_users do
+    override :role, "admin"
+  end
+
+  generate 2
+end

data/examples/base_users.vial.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+vial :base_users, abstract: true do
+  base do
+    active true
+    country "MA"
+    email sequence(:email)
+  end
+
+  sequence(:email) { |i| "base#{i}@test.local" }
+end

data/examples/company__users.vial.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+vial :company__users do
+  base do
+    active true
+    company_id erb("<%= ActiveRecord::FixtureSet.identify(:acme) %>")
+  end
+
+  generate 1
+end

data/examples/users.vial.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+vial :users do
+  base do
+    active true
+    country "MA"
+    email sequence(:email)
+  end
+
+  variant :admin do
+    role "admin"
+  end
+
+  variant :guest do
+    role "guest"
+    active false
+  end
+
+  sequence(:email) { |i| "user#{i}@test.local" }
+
+  generate 2, :admin
+  generate 3, :guest
+end

data/lib/tasks/vial.rake

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+namespace :vial do
+  desc 'Compile Vial sources into Rails fixtures'
+  task :compile, [:only] => :environment do |_, args|
+    only = args[:only] || ENV['ONLY']
+    result = Vial.compile!(only: only)
+    if result && result.status == :compiled
+      puts "Vial: fixtures compiled to #{Vial.config.output_path}"
+    end
+  end
+
+  desc 'Compile Vial sources without writing files (dry run)'
+  task 'compile:dry_run', [:only] => :environment do |_, args|
+    only = args[:only] || ENV['ONLY']
+    result = Vial.compile!(dry_run: true, only: only)
+    return unless result
+
+    if result.status == :dry_run
+      puts "Vial: dry run - would write #{result.files.size} fixture files to #{result.output_path}"
+    end
+  end
+
+  desc 'Compile only selected vials (comma-separated, e.g. vial:compile:only[users,posts])'
+  task 'compile:only', [:names] => :environment do |_, args|
+    names = args[:names] || ENV['ONLY']
+    if names.nil? || names.strip.empty?
+      abort "Usage: bin/rails vial:compile:only[users,posts]"
+    end
+
+    result = Vial.compile!(only: names)
+    if result && result.status == :compiled
+      puts "Vial: fixtures compiled to #{Vial.config.output_path}"
+    end
+  end
+
+  desc 'Remove fixture files generated by Vial that no longer have a matching vial definition'
+  task clean: :environment do
+    result = Vial.clean!
+    return unless result
+
+    if result.status == :cleaned
+      if result.removed.empty?
+        puts "Vial: no stale fixtures to remove"
+      else
+        puts "Vial: removed #{result.removed.size} stale fixture files"
+      end
+    end
+  end
+
+  desc 'Explain a derived ID (format: vial.label.variant[index])'
+  task :explain_id, [:query] => :environment do |_, args|
+    query = args[:query] || ENV['QUERY']
+    if query.nil? || query.strip.empty?
+      abort "Usage: bin/rails vial:explain_id['users.admin.eu[3]']"
+    end
+
+    begin
+      vial_name, label, variants, index = Vial::ExplainId.parse(query)
+    rescue ArgumentError => e
+      abort e.message
+    end
+    Vial.load_sources!
+    definition = Vial.registry[vial_name]
+    abort "Unknown vial: #{vial_name}" unless definition
+
+    info = definition.explain_id(label: label, variant_stack: variants, index: index)
+    puts info[:normalized]
+    puts "hash: #{info[:hash]}"
+    puts "base: #{info[:base]}"
+    puts "range: #{info[:range]}"
+    puts "final: #{info[:final]}"
+  end
+
+  desc 'Count YAML fixture files across all configured fixture paths'
+  task count_fixtures: :environment do
+    # Need to load test environment to get fixture configuration
+    require Rails.root.join('test/test_helper')
+    
+    # Rails 8+ uses fixture_paths as an attribute
+    fixture_paths = ActiveSupport::TestCase.fixture_paths
+
+    puts "Vial: Scanning fixture paths..."
+    puts "Configured paths: #{fixture_paths.join(', ')}"
+    puts
+
+    total_count = 0
+    fixture_counts = {}
+
+    fixture_paths.each do |path|
+      next unless File.directory?(path)
+
+      yaml_files = Dir.glob(File.join(path, '**', '*.yml'))
+      yaml_files += Dir.glob(File.join(path, '**', '*.yaml'))
+      
+      count = yaml_files.size
+      total_count += count
+      
+      puts "#{path}: #{count} YAML files"
+      
+      # Group by subdirectory for better visibility
+      yaml_files.each do |file|
+        relative_path = Pathname.new(file).relative_path_from(Pathname.new(path))
+        dir = relative_path.dirname.to_s
+        fixture_counts[dir] ||= 0
+        fixture_counts[dir] += 1
+      end
+    end
+
+    puts
+    puts "Fixture distribution by directory:"
+    fixture_counts.sort.each do |dir, count|
+      puts "  #{dir == '.' ? '(root)' : dir}: #{count} files"
+    end
+
+    puts
+    puts "Total YAML fixtures found: #{total_count}"
+  end
+  
+  desc 'Analyze fixtures and their model mappings'
+  task analyze_fixtures: :environment do
+    # Ensure test environment is loaded to get fixture configuration
+    require Rails.root.join('test/test_helper')
+    
+    analyzer = Vial::FixtureAnalyzer.new
+    analyzer.analyze
+    
+    puts "=== Vial Fixture Analysis ==="
+    puts
+    
+    summary = analyzer.summary
+    puts "Total fixtures found: #{summary[:total_fixtures]}"
+    puts "Mapped to models: #{summary[:mapped_fixtures]}"
+    puts "Unmapped fixtures: #{summary[:unmapped_fixtures]}"
+    puts
+    
+    if analyzer.mapped_fixtures.any?
+      puts "=== Mapped Fixtures ==="
+      analyzer.mapped_fixtures.sort_by { |k, _| k }.each do |fixture_name, info|
+        puts "#{fixture_name}:"
+        puts "  Model: #{info.model_name}"
+        puts "  Table: #{info.table_name}"
+        puts "  Detection: #{info.detection_method}"
+      end
+      puts
+    end
+    
+    if analyzer.unmapped_fixtures.any?
+      puts "=== Unmapped Fixtures (Potential Issues) ==="
+      analyzer.unmapped_fixtures.sort_by { |k, _| k }.each do |fixture_name, info|
+        puts "#{fixture_name}:"
+        puts "  File: #{info.file}"
+        puts "  Status: No model found"
+      end
+      puts
+    end
+    
+    if summary[:errors].any?
+      puts "=== Errors ==="
+      summary[:errors].each do |error|
+        puts "File: #{error[:file]}"
+        puts "Error: #{error[:error]}"
+        puts
+      end
+    end
+  end
+  
+  desc 'Validate fixtures - check for orphaned fixtures without models'
+  task validate_fixtures: :environment do
+    require Rails.root.join('test/test_helper')
+    
+    analyzer = Vial::FixtureAnalyzer.new
+    analyzer.analyze
+    
+    unmapped = analyzer.unmapped_fixtures
+    
+    if unmapped.empty?
+      puts "✅ All fixtures are properly mapped to models!"
+      exit 0
+    else
+      puts "❌ Found #{unmapped.size} unmapped fixtures:"
+      unmapped.sort_by { |k, _| k }.each do |fixture_name, info|
+        puts "  - #{fixture_name}"
+      end
+      puts
+      puts "These fixtures may:"
+      puts "  1. Need a _fixture: model_class directive in the YAML"
+      puts "  2. Need to be added to set_fixture_class in test_helper.rb"
+      puts "  3. Be orphaned and should be removed"
+      puts "  4. Have a model that doesn't follow Rails naming conventions"
+      
+      exit 1
+    end
+  end
+  
+  desc 'Analyze fixture IDs and check if they use proper ActiveRecord::FixtureSet.identify'
+  task analyze_fixture_ids: :environment do
+    require Rails.root.join('test/test_helper')
+    
+    standardizer = Vial::FixtureIdStandardizer.new
+    standardizer.analyze
+    
+    summary = standardizer.summary
+    
+    puts "=== Vial Fixture ID Analysis ==="
+    puts
+    puts "Total fixtures analyzed: #{summary[:total_fixtures]}"
+    puts "Fixtures needing ID updates: #{summary[:fixtures_needing_updates]}"
+    puts "Total records to update: #{summary[:records_to_update]}"
+    puts
+    
+    if summary[:primary_key_types].any?
+      puts "Primary key types:"
+      summary[:primary_key_types].sort.each do |type, count|
+        puts "  #{type}: #{count} fixtures"
+      end
+      puts
+    end
+    
+    if standardizer.updates_needed.any?
+      puts "=== Fixtures Needing ID Standardization ==="
+      standardizer.updates_needed.each do |update|
+        puts
+        puts "File: #{update.file}"
+        puts "Model: #{update.model_class.name}"
+        puts "Primary Key: #{update.primary_key} (#{update.primary_key_type})"
+        puts "Changes needed:"
+        update.changes.each do |change|
+          puts "  #{change.label}:"
+          puts "    Current: #{change.current_id.inspect}"
+          puts "    Should be: #{change.new_id}"
+        end
+      end
+    else
+      puts "✅ All fixture IDs are properly standardized!"
+    end
+    
+    if summary[:errors].any?
+      puts
+      puts "=== Errors ==="
+      summary[:errors].each do |error|
+        puts "File: #{error[:file]}"
+        puts "Error: #{error[:error]}"
+      end
+    end
+  end
+  
+  desc 'Standardize fixture IDs to use ActiveRecord::FixtureSet.identify'
+  task standardize_fixture_ids: :environment do
+    require Rails.root.join('test/test_helper')
+    
+    standardizer = Vial::FixtureIdStandardizer.new
+    standardizer.analyze
+    
+    summary = standardizer.summary
+    
+    if summary[:records_to_update] == 0
+      puts "✅ All fixture IDs are already standardized!"
+      exit 0
+    end
+    
+    puts "Will update #{summary[:records_to_update]} records across #{summary[:fixtures_needing_updates]} files."
+    puts
+    print "Continue? (y/N): "
+    
+    response = STDIN.gets.chomp.downcase
+    
+    if response == 'y'
+      puts
+      standardizer.standardize!(dry_run: false)
+      puts
+      puts "✅ Fixture IDs have been standardized!"
+    else
+      puts "Cancelled."
+    end
+  end
+  
+  desc 'Dry run of fixture ID standardization (preview changes without applying)'
+  task 'standardize_fixture_ids:dry_run' => :environment do
+    require Rails.root.join('test/test_helper')
+    
+    standardizer = Vial::FixtureIdStandardizer.new
+    standardizer.analyze
+    
+    summary = standardizer.summary
+    
+    puts "=== Vial Fixture ID Standardization (DRY RUN) ==="
+    puts
+    puts "Would update #{summary[:records_to_update]} records across #{summary[:fixtures_needing_updates]} files."
+    puts
+    
+    standardizer.standardize!(dry_run: true)
+    
+    if summary[:errors].any?
+      puts
+      puts "=== Errors ==="
+      summary[:errors].each do |error|
+        puts "File: #{error[:file]}"
+        puts "Error: #{error[:error]}"
+      end
+    end
+  end
+end