synthra 0.1.0

data/lib/synthra/repl/formatter.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+# =============================================================================
+# Synthra Enhanced REPL with Visual Inspection and Debugging
+# =============================================================================
+#
+# Provides enhanced REPL features:
+# - Visual data inspection (table view, JSON pretty-print)
+# - Step-through debugging (pause after each field, show Context state)
+# - Better formatting and display
+#
+# =============================================================================
+
+module Synthra
+  module REPL
+    # Visual formatter for REPL output
+    class Formatter
+      # Format data as a table
+      #
+      # @param data [Hash, Array] data to format
+      # @return [String] formatted table string
+      #
+      def self.table(data)
+        case data
+        when Hash
+          format_hash_table(data)
+        when Array
+          format_array_table(data)
+        else
+          data.inspect
+        end
+      end
+
+      # Format hash as a table
+      #
+      # @param hash [Hash] hash to format
+      # @return [String] formatted table
+      #
+      def self.format_hash_table(hash)
+        return "{}" if hash.empty?
+
+        max_key_width = hash.keys.map { |k| k.to_s.length }.max
+        max_key_width = [max_key_width, 20].min # Cap at 20 chars
+        max_value_width = 60
+
+        lines = []
+        hash.each do |key, value|
+          key_str = key.to_s.ljust(max_key_width)
+          value_str = format_value(value, max_value_width)
+          lines << "  #{key_str} │ #{value_str}"
+        end
+
+        header = "  #{'─' * max_key_width}─┼─#{'─' * max_value_width}"
+        [header, *lines].join("\n")
+      end
+
+      # Format array as a table
+      #
+      # @param array [Array] array to format
+      # @return [String] formatted table
+      #
+      def self.format_array_table(array)
+        return "[]" if array.empty?
+
+        # If array of hashes, show as table
+        if array.first.is_a?(Hash)
+          keys = array.first.keys
+          max_widths = keys.map { |k| [k.to_s.length, array.map { |h| format_value(h[k], 100).length }.max].max }
+          max_widths = max_widths.map { |w| [w, 30].min } # Cap column widths
+
+          # Header
+          header = "  " + keys.map.with_index { |k, i| k.to_s.ljust(max_widths[i]) }.join(" │ ")
+          separator = "  " + max_widths.map { |w| "─" * w }.join("─┼─")
+
+          rows = array.map do |hash|
+            "  " + keys.map.with_index { |k, i| format_value(hash[k], max_widths[i]).ljust(max_widths[i]) }.join(" │ ")
+          end
+
+          [header, separator, *rows].join("\n")
+        else
+          array.map.with_index { |item, i| "  [#{i}] #{format_value(item, 60)}" }.join("\n")
+        end
+      end
+
+      # Format a single value
+      #
+      # @param value [Object] value to format
+      # @param max_width [Integer] maximum width
+      # @return [String] formatted value
+      #
+      def self.format_value(value, max_width = 60)
+        case value
+        when nil
+          "nil"
+        when String
+          if value.length > max_width
+            "#{value[0, max_width - 3]}..."
+          else
+            value.inspect
+          end
+        when Hash
+          if value.empty?
+            "{}"
+          else
+            "{#{value.keys.length} keys}"
+          end
+        when Array
+          if value.empty?
+            "[]"
+          else
+            "[#{value.length} items]"
+          end
+        else
+          str = value.inspect
+          str.length > max_width ? "#{str[0, max_width - 3]}..." : str
+        end
+      end
+
+      # Format context state for debugging
+      #
+      # @param context [Context] context to format
+      # @return [String] formatted context state
+      #
+      def self.format_context(context)
+        lines = []
+        lines << "  Context State:"
+        lines << "  ──────────────"
+        lines << "  Depth: #{context.depth}"
+        lines << "  Registry: #{context.registry ? 'available' : 'none'}"
+        lines << "  Parent Context: #{context.parent_context ? 'yes' : 'no'}"
+        lines << "  Shared Context: #{context.shared_context ? "#{context.shared_context.size} entries" : 'none'}"
+        lines << ""
+        lines << "  Generated Fields:"
+        lines << "  ────────────────"
+        
+        if context.empty?
+          lines << "    (none yet)"
+        else
+          context.each do |key, value|
+            value_str = format_value(value, 50)
+            lines << "    #{key.to_s.ljust(20)} = #{value_str}"
+          end
+        end
+
+        lines.join("\n")
+      end
+    end
+
+    # Debug-enabled engine wrapper
+    class DebugEngine
+      def initialize(schema, registry: nil, mode: :random, seed: nil)
+        @schema = schema
+        @registry = registry
+        @mode = mode
+        @seed = seed
+        @debug_callbacks = []
+      end
+
+      # Add debug callback
+      #
+      # @yield [schema_name, field_name, value, duration_ms] callback block
+      # @note The callback receives 4 arguments matching the engine's on_field_generated signature
+      #
+      def on_field_generated(&block)
+        @debug_callbacks << block
+      end
+
+      # Generate with debugging
+      #
+      # @return [Hash] generated record
+      #
+      def generate
+        # Create a custom configuration that triggers callbacks
+        original_callback = Synthra.configuration.on_field_generated
+        
+        # The engine calls on_field_generated with 4 args: schema_name, field_name, value, duration_ms
+        Synthra.configuration.on_field_generated = lambda do |schema_name, field_name, value, duration_ms|
+          original_callback&.call(schema_name, field_name, value, duration_ms)
+          @debug_callbacks.each { |cb| cb.call(schema_name, field_name, value, duration_ms) }
+        end
+
+        begin
+          engine = Generator::Engine.new(@schema, registry: @registry)
+          engine.generate(seed: @seed, mode: @mode)
+        ensure
+          Synthra.configuration.on_field_generated = original_callback
+        end
+      end
+    end
+  end
+end

data/lib/synthra/scenarios.rb

@@ -0,0 +1,423 @@
+# frozen_string_literal: true
+
+module Synthra
+  # Scenario-based Test Data Fixtures
+  #
+  # Define complex, interconnected test data scenarios that can be
+  # easily reused across tests. Think "Fixtures 2.0" - dynamic,
+  # relationship-aware, and DRY.
+  #
+  # @example Define a scenario
+  #   Synthra::Scenarios.define(:e_commerce_checkout) do
+  #     let(:buyer) { User(role: "customer", verified: true) }
+  #     let(:seller) { User(role: "merchant") }
+  #     let(:laptop) { Product(seller: seller, price: 999.99) }
+  #     let(:cart) { ShoppingCart(user: buyer, items: [laptop]) }
+  #   end
+  #
+  # @example Use in tests
+  #   RSpec.describe "Checkout" do
+  #     include_scenario :e_commerce_checkout
+  #
+  #     it "processes payment" do
+  #       expect(buyer.email).to be_present
+  #       expect(cart.items).to include(laptop)
+  #     end
+  #   end
+  #
+  module Scenarios
+    class << self
+      # Registry of defined scenarios
+      def registry
+        @registry ||= {}
+      end
+
+      # Define a new scenario
+      #
+      # @param name [Symbol] scenario name
+      # @param options [Hash] scenario options
+      # @option options [Symbol] :extends parent scenario to inherit from
+      # @yield scenario definition block
+      # @return [Scenario] the defined scenario
+      #
+      def define(name, **options, &block)
+        scenario = Scenario.new(name, **options)
+        scenario.instance_eval(&block) if block
+        registry[name] = scenario
+        scenario
+      end
+
+      # Get a scenario by name
+      #
+      # @param name [Symbol] scenario name
+      # @return [Scenario, nil] the scenario or nil
+      #
+      def [](name)
+        registry[name]
+      end
+
+      # List all defined scenarios
+      #
+      # @return [Array<Symbol>] scenario names
+      #
+      def list
+        registry.keys
+      end
+
+      # Load scenarios from a file
+      #
+      # @param path [String] path to scenario file
+      #
+      def load_file(path)
+        content = File.read(path)
+        instance_eval(content, path)
+      end
+
+      # Load all scenarios from a directory
+      #
+      # @param dir [String] directory path
+      #
+      def load_dir(dir)
+        Dir.glob(File.join(dir, "**/*.rb")).each do |file|
+          load_file(file)
+        end
+      end
+
+      # Clear all scenarios
+      def reset!
+        @registry = {}
+      end
+    end
+
+    # A scenario definition
+    class Scenario
+      attr_reader :name, :options, :fixtures, :dependencies
+
+      def initialize(name, **options)
+        @name = name
+        @options = options
+        @fixtures = {}
+        @dependencies = []
+        @setup_blocks = []
+        @teardown_blocks = []
+
+        # Inherit from parent scenario
+        if options[:extends]
+          parent = Scenarios[options[:extends]]
+          raise ArgumentError, "Unknown parent scenario: #{options[:extends]}" unless parent
+
+          @fixtures = parent.fixtures.dup
+          @dependencies = parent.dependencies.dup
+        end
+      end
+
+      # Define a named fixture
+      #
+      # @param name [Symbol] fixture name
+      # @param schema [String, Symbol] schema name (optional)
+      # @param options [Hash] generation options
+      # @yield optional customization block
+      # @return [FixtureDefinition] the fixture definition
+      #
+      def let(name, schema = nil, **options, &block)
+        @fixtures[name] = FixtureDefinition.new(name, schema, **options, &block)
+      end
+
+      # Define a lazy fixture (evaluated on first access)
+      #
+      # @param name [Symbol] fixture name
+      # @yield block that returns the fixture value
+      #
+      def let!(name, &block)
+        @fixtures[name] = LazyFixture.new(name, &block)
+      end
+
+      # Define a dependent fixture
+      #
+      # @param schema [String, Symbol] schema to generate
+      # @param name [Symbol] fixture name
+      # @param options [Hash] generation options with references
+      #
+      def create(schema, name = nil, **options)
+        name ||= schema.to_s.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                            .downcase
+                            .to_sym
+        @fixtures[name] = FixtureDefinition.new(name, schema, **options)
+      end
+
+      # Declare a dependency on another scenario
+      #
+      # @param scenario_name [Symbol] name of scenario to include
+      #
+      def depends_on(scenario_name)
+        @dependencies << scenario_name
+      end
+
+      # Add setup block
+      def setup(&block)
+        @setup_blocks << block
+      end
+
+      # Add teardown block
+      def teardown(&block)
+        @teardown_blocks << block
+      end
+
+      # Build the scenario context
+      #
+      # @param seed [Integer] random seed for determinism
+      # @return [ScenarioContext] built context with all fixtures
+      #
+      def build(seed: nil)
+        context = ScenarioContext.new(self, seed: seed)
+
+        # Load dependencies first
+        @dependencies.each do |dep_name|
+          dep = Scenarios[dep_name]
+          raise ArgumentError, "Unknown dependency: #{dep_name}" unless dep
+
+          dep_context = dep.build(seed: seed)
+          context.merge!(dep_context)
+        end
+
+        # Run setup blocks
+        @setup_blocks.each { |block| context.instance_eval(&block) }
+
+        # Build fixtures in dependency order
+        build_order = resolve_build_order
+        build_order.each do |fixture_name|
+          context.build_fixture(fixture_name)
+        end
+
+        context
+      end
+
+      private
+
+      def resolve_build_order
+        # Simple topological sort based on references
+        # For now, just return fixtures in definition order
+        @fixtures.keys
+      end
+    end
+
+    # A fixture definition
+    class FixtureDefinition
+      attr_reader :name, :schema, :options, :block
+
+      def initialize(name, schema = nil, **options, &block)
+        @name = name
+        @schema = schema
+        @options = options
+        @block = block
+      end
+
+      def build(context)
+        # Resolve references in options
+        resolved_options = resolve_references(context)
+
+        # Generate base data
+        if @schema
+          schema_obj = Synthra.registry.schema(@schema.to_s)
+          # :nocov: registry.schema raises KeyError for a missing schema, so this guard is unreachable
+          raise ArgumentError, "Unknown schema: #{@schema}" unless schema_obj
+          # :nocov:
+
+          data = schema_obj.generate(
+            seed: context.seed,
+            overrides: resolved_options
+          )
+        else
+          data = resolved_options
+        end
+
+        # Apply customization block
+        data = @block.call(data, context) if @block
+
+        data
+      end
+
+      private
+
+      def resolve_references(context)
+        resolved = {}
+
+        @options.each do |key, value|
+          resolved[key.to_s] = resolve_value(value, context)
+        end
+
+        resolved
+      end
+
+      def resolve_value(value, context)
+        case value
+        when Symbol
+          # Reference to another fixture
+          context[value] || value.to_s
+        when Proc
+          value.call(context)
+        when Hash
+          value.transform_values { |v| resolve_value(v, context) }
+        when Array
+          value.map { |v| resolve_value(v, context) }
+        else
+          value
+        end
+      end
+    end
+
+    # A lazy fixture that evaluates on first access
+    class LazyFixture
+      attr_reader :name, :block
+
+      def initialize(name, &block)
+        @name = name
+        @block = block
+      end
+
+      def build(context)
+        context.instance_eval(&@block)
+      end
+    end
+
+    # Runtime context for a built scenario
+    class ScenarioContext
+      attr_reader :scenario, :seed, :data
+
+      def initialize(scenario, seed: nil)
+        @scenario = scenario
+        @seed = seed || Random.new_seed
+        @data = {}
+        @built = {}
+      end
+
+      # Access a fixture by name
+      #
+      # @param name [Symbol] fixture name
+      # @return [Object] fixture value
+      #
+      def [](name)
+        @data[name]
+      end
+
+      # Set a fixture value
+      def []=(name, value)
+        @data[name] = value
+      end
+
+      # Build a specific fixture
+      def build_fixture(name)
+        return @data[name] if @built[name]
+
+        fixture_def = @scenario.fixtures[name]
+        return nil unless fixture_def
+
+        @data[name] = fixture_def.build(self)
+        @built[name] = true
+        @data[name]
+      end
+
+      # Merge another context
+      def merge!(other_context)
+        @data.merge!(other_context.data)
+        @built.merge!(other_context.instance_variable_get(:@built))
+      end
+
+      # Convert to hash
+      def to_h
+        @data.dup
+      end
+
+      # Method missing for fixture access
+      def method_missing(name, *args)
+        if @data.key?(name)
+          @data[name]
+        elsif @scenario.fixtures.key?(name)
+          build_fixture(name)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @data.key?(name) || @scenario.fixtures.key?(name) || super
+      end
+    end
+
+    # RSpec integration
+    module RSpecHelpers
+      # Include a scenario in a test
+      #
+      # @param scenario_name [Symbol] name of scenario to include
+      # @param options [Hash] options
+      # @option options [Integer] :seed random seed
+      #
+      def include_scenario(scenario_name, **options)
+        scenario = Scenarios[scenario_name]
+        raise ArgumentError, "Unknown scenario: #{scenario_name}" unless scenario
+
+        let(:scenario_context) { scenario.build(**options) }
+
+        # Define let helpers for each fixture
+        scenario.fixtures.keys.each do |fixture_name|
+          let(fixture_name) { scenario_context[fixture_name] }
+        end
+      end
+
+      # Use scenario data in a before block
+      def use_scenario(scenario_name, **options)
+        before(:each) do
+          scenario = Scenarios[scenario_name]
+          @scenario_context = scenario.build(**options)
+
+          # Make fixtures available as instance variables
+          @scenario_context.data.each do |name, value|
+            instance_variable_set("@#{name}", value)
+          end
+        end
+      end
+    end
+
+    # Minitest integration
+    module MinitestHelpers
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def use_scenario(scenario_name, **options)
+          define_method(:setup_scenario) do
+            scenario = Scenarios[scenario_name]
+            @scenario_context = scenario.build(**options)
+
+            @scenario_context.data.each do |name, value|
+              instance_variable_set("@#{name}", value)
+            end
+          end
+
+          # Hook into setup
+          prepend(Module.new do
+            def setup
+              setup_scenario
+              super
+            end
+          end)
+        end
+      end
+
+      def scenario
+        @scenario_context
+      end
+    end
+  end
+
+  # Register with RSpec if available
+  # :nocov: the `defined?(RSpec)` false arm is unreachable under the test suite (RSpec is always loaded)
+  if defined?(RSpec)
+    RSpec.configure do |config|
+      config.extend Scenarios::RSpecHelpers
+    end
+  end
+  # :nocov:
+end