vial 0.0.0 → 0.2026.1.1.0

data/lib/vial/compiler.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Vial
+  class Compiler
+    CompileResult = Data.define(:status, :files, :output_path)
+    CleanResult = Data.define(:status, :removed)
+    attr_reader :config, :source_paths, :output_path, :seed
+
+    def initialize(config:, source_paths: nil, output_path: nil, seed: nil)
+      @config = config
+      @source_paths = Array(source_paths || config.source_paths)
+      @output_path = output_path || config.output_path
+      @seed = seed || config.seed
+    end
+
+    def compile!(dry_run: false, only: nil)
+      previous_seed = srand(@seed)
+      Vial.load_sources!(source_paths: @source_paths)
+
+      definitions = Vial.registry.definitions
+      if definitions.empty?
+        warn "Vial: no vial definitions found in #{@source_paths.join(', ')}"
+        return CompileResult.new(status: :no_definitions, files: [], output_path: @output_path.to_s)
+      end
+
+      selected_definitions = filter_definitions(definitions, only)
+      if selected_definitions.empty?
+        warn "Vial: no matching vials to compile"
+        return CompileResult.new(status: :no_definitions, files: [], output_path: @output_path.to_s)
+      end
+
+      records_by_definition = definitions.each_with_object([]) do |definition, entries|
+        next if definition.abstract?
+        entries << { definition: definition, records: definition.build_records }
+      end
+
+      total_records = records_by_definition.sum { |entry| entry[:records].size }
+      if total_records == 0
+        warn "Vial: no records generated (all definitions are abstract or missing generate calls)"
+        return CompileResult.new(status: :no_records, files: [], output_path: @output_path.to_s)
+      end
+
+      Validator.new(records_by_definition).validate!
+
+      warn_if_output_path_unconfigured
+
+      selected_names = selected_definitions.map(&:name).to_set
+      selected_records = records_by_definition.select { |entry| selected_names.include?(entry[:definition].name) }
+      files_to_write = selected_records.map { |entry| fixture_path_for(entry[:definition]) }
+
+      if dry_run
+        return CompileResult.new(status: :dry_run, files: files_to_write, output_path: @output_path.to_s)
+      end
+
+      selected_records.each do |entry|
+        write_fixture(entry[:definition], entry[:records])
+      end
+
+      write_manifest(expected_fixture_paths(definitions))
+
+      CompileResult.new(status: :compiled, files: files_to_write, output_path: @output_path.to_s)
+    ensure
+      srand(previous_seed) unless previous_seed.nil?
+    end
+
+    def clean!
+      Vial.load_sources!(source_paths: @source_paths)
+      definitions = Vial.registry.definitions
+      expected = expected_fixture_paths(definitions)
+      manifest = read_manifest
+
+      if manifest.empty?
+        warn "Vial: no manifest found; nothing to clean"
+        return CleanResult.new(status: :no_manifest, removed: [])
+      end
+
+      removed = []
+      manifest.each do |relative_path|
+        next if expected.include?(relative_path)
+
+        file_path = File.join(@output_path.to_s, relative_path)
+        next unless File.exist?(file_path)
+
+        File.delete(file_path)
+        removed << file_path
+      end
+
+      write_manifest(expected)
+      CleanResult.new(status: :cleaned, removed: removed)
+    end
+
+    private
+
+    def write_fixture(definition, records)
+      file_path = File.join(@output_path.to_s, "#{definition.name}.yml")
+      FileUtils.mkdir_p(File.dirname(file_path))
+
+      emitter = YamlEmitter.new(records)
+      File.open(file_path, 'w') do |file|
+        emitter.write_to(file)
+      end
+    end
+
+    def fixture_path_for(definition)
+      File.join(@output_path.to_s, "#{definition.name}.yml")
+    end
+
+    def expected_fixture_paths(definitions)
+      base = Pathname.new(@output_path.to_s)
+      definitions.reject(&:abstract?).map do |definition|
+        Pathname.new(fixture_path_for(definition)).relative_path_from(base).to_s
+      end
+    end
+
+    def manifest_path
+      File.join(@output_path.to_s, '.vial_manifest.yml')
+    end
+
+    def write_manifest(expected_paths)
+      FileUtils.mkdir_p(@output_path.to_s)
+      File.write(manifest_path, YAML.dump(expected_paths))
+    end
+
+    def read_manifest
+      return [] unless File.exist?(manifest_path)
+
+      data = YAML.load_file(manifest_path)
+      data.is_a?(Array) ? data : []
+    rescue
+      []
+    end
+
+    def filter_definitions(definitions, only)
+      filtered = definitions.reject(&:abstract?)
+      return filtered if only.nil?
+
+      names = Array(only).flat_map { |name| name.to_s.split(',') }
+      names = names.map(&:strip).reject(&:empty?).map { |name| name.tr('__', '/') }
+
+      filtered.select { |definition| names.include?(definition.name) }
+    end
+
+    def warn_if_output_path_unconfigured
+      fixture_paths = Array(ActiveSupport::TestCase.fixture_paths).compact.map { |path| File.expand_path(path.to_s) }
+      return if fixture_paths.empty?
+
+      output = File.expand_path(@output_path.to_s)
+
+      return if fixture_paths.any? { |path| output == path || output.start_with?(path + File::SEPARATOR) }
+
+      warn "Vial: output_path (#{@output_path}) is not inside fixture_paths"
+    end
+  end
+end

data/lib/vial/config.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Vial
+  class Config
+    attr_accessor :source_paths, :seed, :id_base, :id_range
+    attr_writer :output_path
+
+    def initialize
+      @source_paths = default_source_paths
+      @output_path = nil
+      @seed = 1
+      @id_base = 0
+      @id_range = 90_000
+    end
+    
+    def output_path
+      @output_path || default_output_path
+    end
+
+    private
+
+    def default_source_paths
+      [Rails.root.join('test/vials')]
+    end
+
+    def default_output_path
+      fixture_paths = Array(ActiveSupport::TestCase.fixture_paths).compact
+      return fixture_paths.first if fixture_paths.any?
+
+      Rails.root.join('test/fixtures')
+    end
+  end
+end

data/lib/vial/definition.rb

@@ -0,0 +1,462 @@
+# frozen_string_literal: true
+
+module Vial
+  class Definition
+    Generation = Data.define(:count, :variant, :label_prefix, :source_file, :source_line)
+    Record = Data.define(:definition, :fixture_label, :identity_label, :variant_stack, :index, :attributes, :source_file, :source_line)
+    SequenceDefinition = Data.define(:start, :block)
+    Include = Data.define(:name, :overrides)
+
+    attr_reader :name, :primary_key, :record_type, :id_base, :id_range, :base_attributes, :variant_attributes
+
+    def initialize(name, primary_key: :id, record_type: nil, id_base: nil, id_range: nil, id_type: nil, abstract: false)
+      @name = normalize_name(name)
+      @primary_key = primary_key.to_s
+      @record_type = (record_type ? record_type.to_s : default_record_type(@name))
+      @id_base = id_base.nil? ? Vial.config.id_base : id_base
+      @id_range = id_range.nil? ? Vial.config.id_range : id_range
+      @abstract = !!abstract
+      raise ArgumentError, "id_type is not supported; Vial derives deterministic integer IDs" unless id_type.nil?
+      raise ArgumentError, "id_range must be positive" unless @id_range.to_i > 0
+      @base_attributes = {}
+      @variant_attributes = {}
+      @generations = []
+      @sequence_defs = {}
+      @includes = []
+      @sequences = nil
+    end
+
+    def base(&block)
+      @base_attributes = build_attributes(&block)
+    end
+
+    def variant(name, &block)
+      @variant_attributes[name.to_sym] = build_attributes(&block)
+    end
+
+    def include_vial(name, &block)
+      overrides = {}
+      if block
+        builder = IncludeOverrideBuilder.new(self)
+        builder.instance_eval(&block)
+        overrides = builder.attributes
+      end
+
+      @includes << Include.new(name: normalize_name(name), overrides: overrides)
+    end
+
+    def generate(*args, **kwargs)
+      count, variant, label_prefix = parse_generation_args(*args, **kwargs)
+      loc = caller_locations(1, 1).first
+      source_file = loc&.absolute_path || loc&.path
+      @generations << Generation.new(
+        count: count,
+        variant: variant,
+        label_prefix: label_prefix,
+        source_file: source_file,
+        source_line: loc&.lineno
+      )
+    end
+
+    def sequence(name, start: 1, &block)
+      if block
+        @sequence_defs[name.to_sym] = SequenceDefinition.new(start: start, block: block)
+        return
+      end
+
+      SequenceRef.new(name)
+    end
+
+    def build_records
+      @sequences = build_sequences
+      base_attrs = resolved_base_attributes
+      records = []
+
+      grouped_generations.each do |group|
+        variant = group[:variant]
+        label = group[:label]
+        count = group[:count]
+        variant_attrs = variant ? (@variant_attributes[variant] || {}) : {}
+        merged_attrs = merge_attributes(base_attrs, variant_attrs)
+        static_attrs, dynamic_entries = split_attributes(merged_attrs)
+        variant_stack = variant ? [variant] : []
+        source_file = group[:source_file]
+        source_line = group[:source_line]
+
+        count.times do |offset|
+          index = offset + 1
+          fixture_label = fixture_label_for(label, index, count)
+
+          attrs = static_attrs.dup
+          if dynamic_entries.any?
+            context = RecordContext.new(self, label: label, variant: variant, index: index)
+            dynamic_entries.each do |key, value|
+              attrs[key] = resolve_value(value, context)
+            end
+          end
+
+          records << Record.new(
+            definition: self,
+            fixture_label: fixture_label,
+            identity_label: label,
+            variant_stack: variant_stack,
+            index: index,
+            attributes: attrs,
+            source_file: source_file,
+            source_line: source_line
+          )
+        end
+      end
+
+      records
+    ensure
+      @sequences = nil
+    end
+
+    def abstract?
+      @abstract
+    end
+
+    def explain_id(label:, variant_stack:, index:)
+      variants = Array(variant_stack)
+      parts = [@name, @record_type, label] + variants + [index]
+      normalized = parts.map { |part| normalize_identity_part(part) }.join('::')
+      hash_value = Zlib.crc32(normalized)
+      {
+        tuple: parts,
+        normalized: normalized,
+        hash: hash_value,
+        base: @id_base,
+        range: @id_range,
+        final: @id_base + (hash_value % @id_range)
+      }
+    end
+
+    def derive_id(label:, variant_stack:, index:, salt: 0)
+      derived_id_for(label: label, variant_stack: variant_stack, index: index, salt: salt)
+    end
+
+    def sequence_definitions
+      @sequence_defs
+    end
+
+    private
+
+    def parse_generation_args(*args, **kwargs)
+      if args.length == 0
+        raise ArgumentError, 'generate requires a count or variant'
+      end
+
+      if args.length == 1
+        if args.first.is_a?(Integer)
+          count = args.first
+          variant = nil
+        else
+          count = 1
+          variant = args.first
+        end
+      else
+        count = args[0]
+        variant = args[1]
+      end
+
+      label_prefix = kwargs[:label_prefix]
+      [count, variant&.to_sym, label_prefix]
+    end
+
+    def build_attributes(&block)
+      builder = AttributeBuilder.new(self)
+      builder.instance_eval(&block) if block
+      builder.attributes
+    end
+
+    def merge_attributes(base, variant)
+      base.merge(variant)
+    end
+
+    def grouped_generations
+      grouped = {}
+
+      @generations.each do |generation|
+        variant = generation.variant
+        label = generation.label_prefix || default_label_prefix(variant)
+        key = [label, variant]
+        entry = grouped[key]
+        if entry
+          entry[:count] += generation.count
+        else
+          grouped[key] = {
+            count: generation.count,
+            source_file: generation.source_file,
+            source_line: generation.source_line
+          }
+        end
+      end
+
+      grouped.keys.sort_by { |label, variant| [label.to_s, variant.to_s] }.map do |label, variant|
+        entry = grouped[[label, variant]]
+        {
+          label: label,
+          variant: variant,
+          count: entry[:count],
+          source_file: entry[:source_file],
+          source_line: entry[:source_line]
+        }
+      end
+    end
+
+    def fixture_label_for(label, index, count)
+      return label.to_s if count == 1
+      "#{label}_#{index}"
+    end
+
+    def resolved_base_attributes(seen = [])
+      if seen.include?(name)
+        raise ArgumentError, "Circular include_vial detected: #{(seen + [name]).join(' -> ')}"
+      end
+
+      seen << name
+      attrs = {}
+
+      @includes.each do |include_entry|
+        included = Vial.registry[include_entry.name]
+        raise ArgumentError, "Unknown include_vial target: #{include_entry.name}" unless included
+
+        attrs = attrs.merge(included.__send__(:resolved_base_attributes, seen))
+        import_sequences_from(included)
+        attrs = attrs.merge(include_entry.overrides)
+      end
+
+      attrs = attrs.merge(@base_attributes)
+      seen.pop
+      attrs
+    end
+
+    def import_sequences_from(definition)
+      definition.sequence_definitions.each do |name, seq_def|
+        @sequence_defs[name] ||= seq_def
+      end
+    end
+
+    def build_sequences
+      @sequence_defs.transform_values do |definition|
+        Sequence.new(start: definition.start, &definition.block)
+      end
+    end
+
+    def resolve_values(attributes, label:, variant:, index:)
+      context = RecordContext.new(self, label: label, variant: variant, index: index)
+      attributes.transform_values do |value|
+        resolve_value(value, context)
+      end
+    end
+
+    def default_label_prefix(variant)
+      variant ? variant.to_s : 'base'
+    end
+
+    def default_record_type(name)
+      base = name.to_s.split('/').last
+      ActiveSupport::Inflector.singularize(base)
+    end
+
+    def normalize_name(name)
+      name.to_s.gsub('__', '/')
+    end
+
+    def normalize_identity_part(value)
+      value.to_s.downcase
+    end
+
+    def derived_id_for(label:, variant_stack:, index:, salt: 0)
+      variants = Array(variant_stack)
+      parts = [@name, @record_type, label] + variants + [index]
+      normalized = parts.map { |part| normalize_identity_part(part) }.join('::')
+      normalized = "#{normalized}::#{salt}" if salt.positive?
+
+      hash_value = Zlib.crc32(normalized)
+      @id_base + (hash_value % @id_range)
+    end
+
+    def resolve_value(value, context)
+      case value
+      when ExplicitId
+        resolved = resolve_value(value.value, context)
+        ExplicitId.new(value: resolved, source_file: value.source_file, source_line: value.source_line)
+      when SequenceRef
+        sequence = @sequences && @sequences[value.name]
+        raise ArgumentError, "Unknown sequence: #{value.name}" unless sequence
+        sequence.next_value
+      when CallableValue
+        resolve_value(value.call(context), context)
+      else
+        value
+      end
+    end
+
+    def split_attributes(attributes)
+      static = {}
+      dynamic = []
+
+      attributes.each do |key, value|
+        if dynamic_attribute?(value)
+          dynamic << [key, value]
+        else
+          static[key] = value
+        end
+      end
+
+      [static, dynamic]
+    end
+
+    def dynamic_attribute?(value)
+      case value
+      in ExplicitId(value:)
+        dynamic_attribute?(value)
+      in SequenceRef | CallableValue
+        true
+      else
+        false
+      end
+    end
+
+    class AttributeBuilder
+      attr_reader :attributes
+
+      def initialize(definition)
+        @definition = definition
+        @attributes = {}
+      end
+
+      def id(value)
+        loc = caller_locations(1, 1).first
+        source_file = loc&.absolute_path || loc&.path
+        @attributes[@definition.primary_key] = ExplicitId.new(
+          value: value,
+          source_file: source_file,
+          source_line: loc&.lineno
+        )
+      end
+
+      def erb(source)
+        Erb.new(source: source)
+      end
+
+      def method_missing(name, *args, &block)
+        if block
+          @attributes[name.to_s] = CallableValue.new(&block)
+          return
+        end
+
+        if args.length != 1
+          raise ArgumentError, "Expected a single value for #{name}"
+        end
+
+        if name.to_s == @definition.primary_key
+          loc = caller_locations(1, 1).first
+          source_file = loc&.absolute_path || loc&.path
+          @attributes[name.to_s] = ExplicitId.new(
+            value: args.first,
+            source_file: source_file,
+            source_line: loc&.lineno
+          )
+        else
+          @attributes[name.to_s] = args.first
+        end
+      end
+
+      def respond_to_missing?(*_args)
+        true
+      end
+
+      def sequence(name, start: 1, &block)
+        @definition.sequence(name, start: start, &block)
+      end
+    end
+
+    class IncludeOverrideBuilder
+      attr_reader :attributes
+
+      def initialize(definition)
+        @definition = definition
+        @attributes = {}
+      end
+
+      def erb(source)
+        Erb.new(source: source)
+      end
+
+      def id(value)
+        loc = caller_locations(1, 1).first
+        source_file = loc&.absolute_path || loc&.path
+        @attributes[@definition.primary_key] = ExplicitId.new(
+          value: value,
+          source_file: source_file,
+          source_line: loc&.lineno
+        )
+      end
+
+      def override(name, value = nil, &block)
+        if block
+          if name.to_s == @definition.primary_key
+            loc = caller_locations(1, 1).first
+            source_file = loc&.absolute_path || loc&.path
+            @attributes[name.to_s] = ExplicitId.new(
+              value: CallableValue.new(&block),
+              source_file: source_file,
+              source_line: loc&.lineno
+            )
+          else
+            @attributes[name.to_s] = CallableValue.new(&block)
+          end
+          return
+        end
+
+        if name.to_s == @definition.primary_key
+          loc = caller_locations(1, 1).first
+          source_file = loc&.absolute_path || loc&.path
+          @attributes[name.to_s] = ExplicitId.new(
+            value: value,
+            source_file: source_file,
+            source_line: loc&.lineno
+          )
+        else
+          @attributes[name.to_s] = value
+        end
+      end
+
+      def sequence(name, start: 1, &block)
+        @definition.sequence(name, start: start, &block)
+      end
+    end
+
+    class CallableValue
+      def initialize(&block)
+        @block = block
+      end
+
+      def call(context)
+        @block.call(context)
+      end
+    end
+
+    class RecordContext
+      attr_reader :label, :variant, :index
+
+      def initialize(definition, label:, variant:, index:)
+        @definition = definition
+        @label = label
+        @variant = variant
+        @index = index
+      end
+
+      def sequence(name)
+        @definition.sequence(name)
+      end
+
+      def erb(source)
+        Erb.new(source: source)
+      end
+    end
+  end
+end

data/lib/vial/dsl.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Vial
+  module DSL
+    def vial(name, **options, &block)
+      Vial.define(name, **options, &block)
+    end
+  end
+end

data/lib/vial/erb.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Vial
+  Erb = Data.define(:source)
+end

data/lib/vial/explain_id.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Vial
+  module ExplainId
+    module_function
+
+    def parse(query)
+      query = query.to_s.strip
+      match = query.match(/\[(\d+)\]\s*\z/)
+      index = match ? match[1].to_i : 1
+      query = query.sub(/\[(\d+)\]\s*\z/, '')
+
+      parts = query.split('.').map(&:strip).reject(&:empty?)
+      raise ArgumentError, "Invalid explain_id query: #{query}" if parts.length < 2
+
+      vial_name = normalize_vial_name(parts.shift)
+      label = parts.shift
+      variants = parts
+
+      [vial_name, label, variants, index]
+    end
+
+    def normalize_vial_name(name)
+      name.to_s.gsub('__', '/')
+    end
+  end
+end

data/lib/vial/explicit_id.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Vial
+  ExplicitId = Data.define(:value, :source_file, :source_line)
+end