synthra 0.1.0

data/lib/synthra/schema_versioning.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Synthra
+  # Schema Versioning Support
+  #
+  # Track schema versions and migration paths for API evolution.
+  #
+  # @example DSL syntax
+  #   User@v1:
+  #     id: uuid
+  #     name: name
+  #
+  #   User@v2:
+  #     @migrated_from User@v1
+  #     id: uuid
+  #     first_name: name
+  #     last_name: name
+  #
+  module SchemaVersioning
+    # Parse version from schema name
+    #
+    # @param name [String] schema name with optional version
+    # @return [Hash] { name: String, version: String|nil }
+    #
+    # @example
+    #   parse_version("User@v2")
+    #   # => { name: "User", version: "v2" }
+    #
+    def self.parse_version(name)
+      if name.include?("@")
+        parts = name.split("@", 2)
+        { name: parts[0], version: parts[1] }
+      else
+        { name: name, version: nil }
+      end
+    end
+
+    # Generate schema key for registry
+    #
+    # @param name [String] schema name
+    # @param version [String, nil] version
+    # @return [String] registry key
+    #
+    def self.registry_key(name, version = nil)
+      version ? "#{name}@#{version}" : name
+    end
+
+    # Version registry for tracking migrations
+    class Registry
+      class << self
+        def instance
+          @instance ||= new
+        end
+
+        def register(from:, to:, changes: {})
+          instance.register(from: from, to: to, changes: changes)
+        end
+
+        def get_migration(from, to)
+          instance.get_migration(from, to)
+        end
+
+        def migration_path(from, to)
+          instance.migration_path(from, to)
+        end
+
+        def versions_for(schema_name)
+          instance.versions_for(schema_name)
+        end
+
+        def clear
+          instance.clear
+        end
+      end
+
+      def initialize
+        @migrations = {}
+        @versions = Hash.new { |h, k| h[k] = [] }
+        @mutex = Mutex.new
+      end
+
+      # Register a migration from one version to another
+      #
+      # @param from [String] source version (e.g., "User@v1")
+      # @param to [String] target version (e.g., "User@v2")
+      # @param changes [Hash] migration changes
+      #
+      def register(from:, to:, changes: {})
+        @mutex.synchronize do
+          @migrations[[from, to]] = changes
+          
+          # Track versions
+          from_parsed = SchemaVersioning.parse_version(from)
+          to_parsed = SchemaVersioning.parse_version(to)
+          
+          @versions[from_parsed[:name]] << from_parsed[:version]
+          @versions[to_parsed[:name]] << to_parsed[:version]
+          @versions[from_parsed[:name]].uniq!
+          @versions[to_parsed[:name]].uniq!
+        end
+      end
+
+      # Get migration between two versions
+      #
+      # @param from [String] source version
+      # @param to [String] target version
+      # @return [Hash, nil] migration info
+      #
+      def get_migration(from, to)
+        @mutex.synchronize { @migrations[[from, to]] }
+      end
+
+      # Get all versions for a schema
+      #
+      # @param schema_name [String] schema name without version
+      # @return [Array<String>] versions
+      #
+      def versions_for(schema_name)
+        @mutex.synchronize { @versions[schema_name].sort }
+      end
+
+      # Find migration path between versions
+      #
+      # @param from [String] source version
+      # @param to [String] target version
+      # @return [Array<Array>] path of migrations
+      #
+      def migration_path(from, to)
+        @mutex.synchronize do
+          # Simple BFS to find path
+          visited = Set.new
+          queue = [[from, []]]
+
+          while queue.any?
+            current, path = queue.shift
+            return path if current == to
+            next if visited.include?(current)
+            
+            visited.add(current)
+            
+            @migrations.keys.each do |from_key, to_key|
+              if from_key == current && !visited.include?(to_key)
+                queue << [to_key, path + [[from_key, to_key]]]
+              end
+            end
+          end
+
+          nil # No path found
+        end
+      end
+
+      def clear
+        @mutex.synchronize do
+          @migrations.clear
+          @versions.clear
+        end
+      end
+    end
+
+    # Migration analyzer
+    class Analyzer
+      # Detect breaking changes between two schemas
+      #
+      # @param old_schema [Schema] old version
+      # @param new_schema [Schema] new version
+      # @return [Hash] analysis results
+      #
+      def self.analyze(old_schema, new_schema)
+        old_fields = old_schema.fields.map(&:name)
+        new_fields = new_schema.fields.map(&:name)
+
+        removed_fields = old_fields - new_fields
+        added_fields = new_fields - old_fields
+        common_fields = old_fields & new_fields
+
+        type_changes = []
+        common_fields.each do |name|
+          old_field = old_schema.field(name)
+          new_field = new_schema.field(name)
+          
+          if old_field.type_name != new_field.type_name
+            type_changes << {
+              field: name,
+              from: old_field.type_name,
+              to: new_field.type_name
+            }
+          end
+        end
+
+        {
+          breaking: removed_fields.any? || type_changes.any?,
+          removed_fields: removed_fields,
+          added_fields: added_fields,
+          type_changes: type_changes,
+          summary: generate_summary(removed_fields, added_fields, type_changes)
+        }
+      end
+
+      private
+
+      def self.generate_summary(removed, added, type_changes)
+        parts = []
+        parts << "Removed: #{removed.join(', ')}" if removed.any?
+        parts << "Added: #{added.join(', ')}" if added.any?
+        type_changes.each do |change|
+          parts << "Changed #{change[:field]}: #{change[:from]} → #{change[:to]}"
+        end
+        parts.join("\n")
+      end
+    end
+  end
+end

data/lib/synthra/snapshot_testing.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Synthra
+  # Snapshot Testing Support
+  #
+  # Provides helpers for snapshot testing generated data.
+  # Ensures schema changes are detected and intentional.
+  #
+  # @example RSpec integration
+  #   RSpec.describe "Schema Snapshots" do
+  #     include Synthra::SnapshotTesting
+  #
+  #     Synthra.each_schema do |schema|
+  #       it "#{schema.name} generates stable output" do
+  #         expect_snapshot(schema, seed: 42)
+  #       end
+  #     end
+  #   end
+  #
+  module SnapshotTesting
+    # Default snapshot directory
+    SNAPSHOT_DIR = "spec/snapshots/synthra"
+
+    class << self
+      # Snapshot directory path
+      attr_accessor :snapshot_dir
+    end
+
+    self.snapshot_dir = SNAPSHOT_DIR
+
+    # Generate and compare snapshot for a schema
+    #
+    # @param schema [Schema] the schema to snapshot
+    # @param seed [Integer] seed for deterministic generation
+    # @param update [Boolean] if true, update the snapshot file
+    # @return [Boolean] true if snapshot matches
+    #
+    def expect_snapshot(schema, seed: 42, update: false)
+      snapshot_path = snapshot_path_for(schema)
+      generated = schema.generate(seed: seed)
+      generated_json = JSON.pretty_generate(sort_hash(generated))
+
+      if update || !File.exist?(snapshot_path)
+        write_snapshot(snapshot_path, generated_json)
+        return true
+      end
+
+      expected = File.read(snapshot_path)
+      
+      if generated_json == expected
+        true
+      else
+        report_snapshot_mismatch(schema.name, expected, generated_json)
+        false
+      end
+    end
+
+    # RSpec matcher for snapshot testing
+    #
+    # @param schema_name [String] schema name for snapshot file
+    # @return [SnapshotMatcher]
+    #
+    def match_snapshot(schema_name)
+      SnapshotMatcher.new(schema_name, snapshot_dir: SnapshotTesting.snapshot_dir)
+    end
+
+    # Generate snapshots for all schemas
+    #
+    # @param registry [Registry] schema registry
+    # @param seed [Integer] seed for deterministic generation
+    #
+    def self.generate_all_snapshots(registry, seed: 42)
+      FileUtils.mkdir_p(snapshot_dir)
+      
+      registry.schemas.each do |name, schema|
+        path = File.join(snapshot_dir, "#{name.downcase}.json")
+        generated = schema.generate(seed: seed)
+        File.write(path, JSON.pretty_generate(deep_sort(generated)))
+        puts "Generated snapshot: #{path}"
+      end
+    end
+
+    # Verify all snapshots match
+    #
+    # @param registry [Registry] schema registry
+    # @param seed [Integer] seed for deterministic generation
+    # @return [Array<String>] list of mismatched schema names
+    #
+    def self.verify_all_snapshots(registry, seed: 42)
+      mismatches = []
+      
+      registry.schemas.each do |name, schema|
+        path = File.join(snapshot_dir, "#{name.downcase}.json")
+        
+        unless File.exist?(path)
+          mismatches << "#{name}: snapshot not found"
+          next
+        end
+        
+        generated = schema.generate(seed: seed)
+        expected = JSON.parse(File.read(path))
+        
+        unless deep_sort(generated) == deep_sort(expected)
+          mismatches << name
+        end
+      end
+      
+      mismatches
+    end
+
+    # Deep sort helper for module methods
+    def self.deep_sort(obj)
+      case obj
+      when Hash
+        obj.sort.to_h.transform_values { |v| deep_sort(v) }
+      when Array
+        obj.map { |v| deep_sort(v) }
+      else
+        obj
+      end
+    end
+
+    private
+
+    def snapshot_path_for(schema)
+      dir = SnapshotTesting.snapshot_dir
+      FileUtils.mkdir_p(dir)
+      File.join(dir, "#{schema.name.downcase}.json")
+    end
+
+    def write_snapshot(path, content)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, content)
+    end
+
+    def sort_hash(obj)
+      case obj
+      when Hash
+        obj.sort.to_h.transform_values { |v| sort_hash(v) }
+      when Array
+        obj.map { |v| sort_hash(v) }
+      else
+        obj
+      end
+    end
+
+    def report_snapshot_mismatch(name, expected, actual)
+      puts "\nSnapshot mismatch for #{name}:"
+      puts "Expected:"
+      puts expected.lines.first(10).join
+      puts "..."
+      puts "\nActual:"
+      puts actual.lines.first(10).join
+      puts "..."
+    end
+
+    # RSpec matcher class
+    class SnapshotMatcher
+      def initialize(schema_name, snapshot_dir:)
+        @schema_name = schema_name
+        @snapshot_dir = snapshot_dir
+      end
+
+      def matches?(actual)
+        @actual = actual
+        path = File.join(@snapshot_dir, "#{@schema_name.downcase}.json")
+        
+        return false unless File.exist?(path)
+        
+        @expected = JSON.parse(File.read(path))
+        sorted_actual = sort_hash(@actual)
+        sorted_expected = sort_hash(@expected)
+        
+        sorted_actual == sorted_expected
+      end
+
+      def failure_message
+        "expected generated data to match snapshot for #{@schema_name}"
+      end
+
+      def failure_message_when_negated
+        "expected generated data not to match snapshot for #{@schema_name}"
+      end
+
+      private
+
+      def sort_hash(obj)
+        case obj
+        when Hash
+          obj.sort.to_h.transform_values { |v| sort_hash(v) }
+        when Array
+          obj.map { |v| sort_hash(v) }
+        else
+          obj
+        end
+      end
+    end
+  end
+end