synthra 0.1.0

data/lib/synthra/cli.rb

@@ -0,0 +1,2471 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Command Line Interface
+# =============================================================================
+#
+# Provides a command-line interface for validating schemas and generating
+# fake data. The CLI supports multiple output formats and generation modes.
+#
+# @example Validate a schema
+#   $ synthra validate schemas/user.dsl
+#   Schema valid: schemas/user.dsl
+#
+# @example Generate fake data
+#   $ synthra generate User --dir schemas --count 10 --pretty
+#
+# @example Generate NDJSON for streaming
+#   $ synthra generate User --dir schemas --count 1000 --ndjson
+#
+# =============================================================================
+
+
+require "optparse"
+require "fileutils"
+
+module Synthra
+
+  # Command-line interface for Synthra
+  #
+  # The CLI provides commands for schema validation and data generation.
+  # It supports multiple output formats (JSON, NDJSON) and generation
+  # modes (random, edge, invalid, mixed).
+  #
+  # Commands:
+  # - `validate <path>`: Check if a DSL file is syntactically valid
+  # - `lint <path|dir>`: Lint schemas for path errors, missing fields, etc.
+  # - `generate <SchemaName>`: Generate fake data for a schema
+  #
+  # @example Run the CLI
+  #   cli = CLI.new(ARGV)
+  #   exit_code = cli.run
+  #
+
+  class CLI
+
+    # Exit code for successful execution
+    # @return [Integer] 0
+    EXIT_SUCCESS = 0
+
+    # Exit code for parse/validation errors
+    # @return [Integer] 1
+    EXIT_PARSE_ERROR = 1
+
+    # Exit code for runtime errors
+    # @return [Integer] 2
+    EXIT_RUNTIME_ERROR = 2
+
+    # Create a new CLI instance
+    #
+    # @param args [Array<String>] command-line arguments (typically ARGV)
+    #
+    # @example
+    #   cli = CLI.new(["generate", "User", "--count", "10"])
+    #
+
+    def initialize(args)
+      @args = args
+      @options = {
+        count: 1,           # Number of records to generate
+        mode: :random,      # Generation mode
+        format: :json,      # Output format
+        pretty: false,      # Pretty-print JSON
+        dir: "."            # Directory containing .dsl files
+      }
+    end
+
+    # Run the CLI command
+    #
+    # Parses the command and options, executes the appropriate command,
+    # and returns an exit code.
+    #
+    # @return [Integer] exit code (0 = success, 1 = parse error, 2 = runtime error)
+    #
+    # @example
+    #   exit_code = cli.run
+    #   exit(exit_code)
+    #
+
+    def run
+      return show_help if @args.empty?
+
+      command = @args.shift
+      case command
+      when "validate"
+        validate_command
+      when "lint"
+        lint_command
+      when "preview"
+        preview_command
+      when "generate"
+        generate_command
+      when "info"
+        info_command
+      when "diff"
+        diff_command
+      when "repl"
+        repl_command  # :nocov:
+      when "export"
+        export_command
+      when "graph"
+        graph_command
+      when "watch"
+        watch_command  # :nocov:
+      when "lsp"
+        lsp_command
+      when "import"
+        import_command
+      when "docs"
+        docs_command
+      when "live"
+        live_command  # :nocov:
+      when "seed"
+        seed_command
+      when "server"
+        server_command  # :nocov:
+      when "contracts"
+        contracts_command
+      when "perf"
+        perf_command
+      when "--help", "-h", "help"
+        show_help
+      when "--version", "-v"
+        show_version
+      else
+        $stderr.puts "Unknown command: #{command}"
+        $stderr.puts "Run 'synthra --help' for usage information."
+        EXIT_PARSE_ERROR
+      end
+    rescue Synthra::Errors::ParseError => e
+      $stderr.puts "Parse error: #{e.message}"
+      EXIT_PARSE_ERROR
+    rescue Synthra::Errors::Error => e
+      $stderr.puts "Error: #{e.message}"
+      EXIT_RUNTIME_ERROR
+    rescue Errno::ENOENT => e
+      $stderr.puts "File not found: #{e.message}"
+      EXIT_PARSE_ERROR
+    end
+
+    private
+
+    # Execute the validate command
+    #
+    # Loads and parses a DSL file to check for syntax errors.
+    # Prints success message or error details.
+    #
+    # @return [Integer] exit code
+    #
+
+    def validate_command
+      parse_validate_options
+      path = @args.shift
+
+      unless path
+        $stderr.puts "Usage: synthra validate <path>"
+        return EXIT_PARSE_ERROR
+      end
+
+      registry = Registry.new
+      registry.load_file(path)
+      puts "Schema valid: #{path}"
+      EXIT_SUCCESS
+    end
+
+    # Execute the lint command
+    #
+    # Loads schemas and checks for semantic errors:
+    # - Invalid copy() paths
+    # - Missing map_by_field key fields
+    # - Undefined schema references
+    # - Potential typos with suggestions
+    #
+    # @return [Integer] exit code
+    #
+
+    def lint_command
+      parse_lint_options
+      path = @args.shift
+
+      unless path
+        $stderr.puts "Usage: synthra lint <path|directory>"
+        return EXIT_PARSE_ERROR
+      end
+
+      registry = Registry.new
+
+      # Load schemas without automatic validation (we'll validate manually for better output)
+      if File.directory?(path)
+        load_schemas_from_dir_no_validate(registry, path)
+      else
+        registry.load_file(path, validate: false)
+      end
+
+      # Run validation and collect errors
+      errors = registry.validate_paths
+
+      if errors.empty?
+        puts "✓ No lint errors found in #{registry.size} schema(s)"
+        if @options[:verbose]
+          puts "\nSchemas checked:"
+          registry.names.sort.each { |name| puts "  - #{name}" }
+        end
+        EXIT_SUCCESS
+      else
+        puts "✗ Found #{errors.length} lint error(s):\n\n"
+
+        errors.each_with_index do |error, i|
+          puts "#{i + 1}. #{error.message}"
+          # :nocov:
+          if error.respond_to?(:suggestions) && error.suggestions&.any?
+            puts "   Did you mean: #{error.suggestions.first(3).join(", ")}?"
+          end
+          # :nocov:
+          puts
+        end
+
+        # In strict mode, treat warnings as errors
+        if @options[:strict]
+          $stderr.puts "Strict mode: #{errors.length} error(s) treated as failures"
+        end
+
+        EXIT_PARSE_ERROR
+      end
+    end
+
+    # Execute the preview command
+    #
+    # Generates a single record for quick schema testing.
+    # Always outputs pretty-printed JSON with schema info header.
+    #
+    # @return [Integer] exit code
+    #
+
+    def preview_command
+      parse_preview_options
+      schema_name = @args.shift
+
+      unless schema_name
+        $stderr.puts "Usage: synthra preview <SchemaName> [options]"
+        return EXIT_PARSE_ERROR
+      end
+
+      registry = Registry.new
+      load_schemas_from_dir(registry, @options[:dir])
+
+      schema = registry.schema(schema_name)
+      
+      # Generate single record
+      options = { registry: registry, mode: @options[:mode] }
+      options[:seed] = @options[:seed] if @options[:seed]
+      
+      record = schema.generate(**options)
+
+      # Output with header
+      puts "# #{schema_name} (#{schema.fields.length} fields)"
+      puts JSON.pretty_generate(record)
+      
+      EXIT_SUCCESS
+    rescue KeyError
+      $stderr.puts "Unknown schema: #{schema_name}"
+      $stderr.puts "Available schemas: #{registry.schemas.keys.join(", ")}"
+      EXIT_PARSE_ERROR
+    end
+
+    # Execute the info command
+    #
+    # Shows information about schemas including version, fields, and deprecation status.
+    #
+    # @return [Integer] exit code
+    #
+
+    def info_command
+      parse_info_options
+      path = @args.shift
+
+      unless path
+        $stderr.puts "Usage: synthra info <path|directory> [options]"
+        return EXIT_PARSE_ERROR
+      end
+
+      registry = Registry.new
+
+      if File.directory?(path)
+        load_schemas_from_dir_no_validate(registry, path)
+      else
+        registry.load_file(path, validate: false)
+      end
+
+      schemas = registry.schemas
+
+      if schemas.empty?
+        puts "No schemas found."
+        return EXIT_SUCCESS
+      end
+
+      puts "=" * 60
+      puts "Schema Information"
+      puts "=" * 60
+      puts
+
+      schemas.each do |name, schema|
+        puts "📦 #{name}"
+        puts "   Version: #{schema.version || 'not specified'}"
+        puts "   Fields: #{schema.fields.length}"
+        puts "   Behaviors: #{schema.behaviors.length}"
+        
+        # :nocov:
+        if schema.deprecated?
+          puts "   ⚠️  DEPRECATED: #{schema.deprecation_message || 'No message'}"
+        end
+        # :nocov:
+        
+        if @options[:verbose]
+          puts "   Field list:"
+          schema.fields.each do |field|
+            optional = field.optional? ? "?" : ""
+            nullable = field.nullable? ? "?" : ""
+            puts "     - #{field.name}#{optional}: #{field.type_name}#{nullable}"
+          end
+        end
+        puts
+      end
+
+      EXIT_SUCCESS
+    end
+
+    # Execute the diff command
+    #
+    # Compares two schema files/directories and shows differences.
+    #
+    # @return [Integer] exit code
+    #
+
+    def diff_command
+      parse_diff_options
+      path1 = @args.shift
+      path2 = @args.shift
+
+      unless path1 && path2
+        $stderr.puts "Usage: synthra diff <path1> <path2>"
+        return EXIT_PARSE_ERROR
+      end
+
+      registry1 = Registry.new
+      registry2 = Registry.new
+
+      load_path(registry1, path1)
+      load_path(registry2, path2)
+
+      schemas1 = registry1.schemas
+      schemas2 = registry2.schemas
+
+      all_names = (schemas1.keys + schemas2.keys).uniq.sort
+
+      puts "=" * 60
+      puts "Schema Diff"
+      puts "=" * 60
+      puts
+
+      has_diff = false
+
+      all_names.each do |name|
+        s1 = schemas1[name]
+        s2 = schemas2[name]
+
+        if s1.nil?
+          puts "➕ #{name} (added in #{path2})"
+          has_diff = true
+        elsif s2.nil?
+          puts "➖ #{name} (removed in #{path2})"
+          has_diff = true
+        else
+          diff = compare_schemas(s1, s2)
+          if diff.any?
+            puts "📝 #{name} (modified)"
+            diff.each { |d| puts "   #{d}" }
+            has_diff = true
+          end
+        end
+      end
+
+      puts "✅ No differences found." unless has_diff
+      EXIT_SUCCESS
+    end
+
+    # Execute the repl command
+    #
+    # Starts an interactive REPL for testing schemas.
+    #
+    # @return [Integer] exit code
+    #
+
+    # :nocov:
+    def repl_command
+      parse_repl_options
+      require_relative "repl/formatter"
+      
+      puts "=" * 60
+      puts "Synthra Interactive REPL (Enhanced)"
+      puts "=" * 60
+      puts
+      puts "Commands:"
+      puts "  load <path>        - Load schemas from file/directory"
+      puts "  list               - List loaded schemas"
+      puts "  info <Schema>      - Show schema details"
+      puts "  gen <Schema>       - Generate one record (JSON)"
+      puts "  gen <Schema> N     - Generate N records (JSON)"
+      puts "  table <Schema>     - Generate one record (table view)"
+      puts "  table <Schema> N   - Generate N records (table view)"
+      puts "  debug <Schema>     - Step-through debug generation"
+      puts "  inspect <Schema>   - Generate and show detailed inspection"
+      puts "  seed <number>      - Set seed for deterministic output"
+      puts "  mode <mode>        - Set mode (random/edge/invalid/hostile/mixed)"
+      puts "  help               - Show this help"
+      puts "  quit/exit          - Exit REPL"
+      puts
+
+      registry = Registry.new
+      current_seed = nil
+      current_mode = :random
+
+      loop do
+        print "synthra> "
+        input = $stdin.gets&.strip
+        break if input.nil?
+
+        case input
+        when /^load\s+(.+)$/
+          path = $1.strip
+          begin
+            if File.directory?(path)
+              load_schemas_from_dir_no_validate(registry, path)
+            else
+              registry.load_file(path, validate: false)
+            end
+            puts "✅ Loaded #{registry.size} schema(s)"
+          rescue => e
+            puts "❌ Error: #{e.message}"
+          end
+
+        when "list"
+          if registry.size == 0
+            puts "No schemas loaded. Use 'load <path>' first."
+          else
+            puts "Loaded schemas:"
+            registry.schemas.each do |name, schema|
+              version = schema.version ? " v#{schema.version}" : ""
+              deprecated = schema.deprecated? ? " [DEPRECATED]" : ""
+              puts "  - #{name}#{version}#{deprecated}"
+            end
+          end
+
+        when /^info\s+(\w+)$/
+          name = $1
+          begin
+            schema = registry.schema(name)
+            puts "Schema: #{name}"
+            puts "  Version: #{schema.version || 'not specified'}"
+            puts "  Fields: #{schema.fields.length}"
+            schema.fields.each do |f|
+              optional = f.optional? ? "?" : ""
+              nullable = f.nullable? ? " (nullable)" : ""
+              puts "    - #{f.name}#{optional}: #{f.type_name}#{nullable}"
+            end
+          rescue KeyError
+            puts "❌ Schema '#{name}' not found"
+          end
+
+        when /^gen\s+(\w+)(?:\s+(\d+))?$/
+          name = $1
+          count = ($2 || "1").to_i
+          begin
+            schema = registry.schema(name)
+            opts = { registry: registry, mode: current_mode }
+            opts[:seed] = current_seed if current_seed
+            
+            if count == 1
+              record = schema.generate(**opts)
+              puts JSON.pretty_generate(record)
+            else
+              records = schema.generate_many(count, **opts)
+              puts JSON.pretty_generate(records)
+            end
+          rescue KeyError
+            puts "❌ Schema '#{name}' not found"
+          rescue => e
+            puts "❌ Error: #{e.message}"
+            puts e.backtrace.first(3).join("\n") if @options[:verbose]
+          end
+
+        when /^table\s+(\w+)(?:\s+(\d+))?$/
+          name = $1
+          count = ($2 || "1").to_i
+          begin
+            schema = registry.schema(name)
+            opts = { registry: registry, mode: current_mode }
+            opts[:seed] = current_seed if current_seed
+            
+            if count == 1
+              record = schema.generate(**opts)
+              puts REPL::Formatter.table(record)
+            else
+              records = schema.generate_many(count, **opts)
+              puts REPL::Formatter.table(records)
+            end
+          rescue KeyError
+            puts "❌ Schema '#{name}' not found"
+          rescue => e
+            puts "❌ Error: #{e.message}"
+          end
+
+        when /^debug\s+(\w+)$/
+          name = $1
+          begin
+            schema = registry.schema(name)
+            debug_generation(schema, registry, current_mode, current_seed)
+          rescue KeyError
+            puts "❌ Schema '#{name}' not found"
+          rescue => e
+            puts "❌ Error: #{e.message}"
+          end
+
+        when /^inspect\s+(\w+)$/
+          name = $1
+          begin
+            schema = registry.schema(name)
+            opts = { registry: registry, mode: current_mode }
+            opts[:seed] = current_seed if current_seed
+            
+            record = schema.generate(**opts)
+            puts "📊 Generated Record:"
+            puts "=" * 60
+            puts REPL::Formatter.table(record)
+            puts
+            puts "📋 JSON Format:"
+            puts JSON.pretty_generate(record)
+            puts
+            puts "📏 Statistics:"
+            puts "  Fields: #{record.keys.length}"
+            puts "  Total size: #{JSON.generate(record).bytesize} bytes"
+            record.each do |key, value|
+              type = value.class.name
+              size = case value
+                     when String then value.bytesize
+                     when Hash then "#{value.keys.length} keys"
+                     when Array then "#{value.length} items"
+                     else value.inspect.length
+                     end
+              puts "    #{key}: #{type} (#{size})"
+            end
+          rescue KeyError
+            puts "❌ Schema '#{name}' not found"
+          rescue => e
+            puts "❌ Error: #{e.message}"
+          end
+
+        when /^seed\s+(\d+)$/
+          current_seed = $1.to_i
+          puts "✅ Seed set to #{current_seed}"
+
+        when /^mode\s+(random|edge|invalid|hostile|mixed)$/
+          current_mode = $1.to_sym
+          puts "✅ Mode set to #{current_mode}"
+
+        when "help"
+          puts "Commands: load, list, info, gen, table, debug, inspect, seed, mode, help, quit"
+
+        when "quit", "exit"
+          puts "Goodbye!"
+          break
+
+        when ""
+          # Ignore empty input
+
+        else
+          puts "Unknown command. Type 'help' for available commands."
+        end
+      end
+
+      EXIT_SUCCESS
+    end
+
+    # Debug generation with step-through
+    #
+    # @param schema [Schema] schema to generate from
+    # @param registry [Registry] schema registry
+    # @param mode [Symbol] generation mode
+    # @param seed [Integer, nil] seed for determinism
+    #
+    def debug_generation(schema, registry, mode, seed)
+      puts "🐛 Debug Mode: Generating #{schema.name}"
+      puts "=" * 60
+      puts "Press Enter to continue after each field, 'q' to quit, 'c' to continue without pausing"
+      puts
+
+      field_index = 0
+      context_snapshot = nil
+
+      # Set up callback to intercept field generation
+      original_callback = Synthra.configuration.on_field_generated
+      
+      Synthra.configuration.on_field_generated = lambda do |schema_name, field_name, value, duration|
+        field_index += 1
+        
+        puts "\n[Field #{field_index}] #{field_name}"
+        puts "─" * 60
+        puts "Value: #{REPL::Formatter.format_value(value, 80)}"
+        puts "Duration: #{duration}ms" if duration
+        puts "Schema: #{schema_name}"
+        puts
+        
+        loop do
+          print "Press Enter to continue, 'q' to quit, 'c' to continue without pausing: "
+          response = $stdin.gets&.strip&.downcase
+          
+          case response
+          when "q", "quit"
+            Synthra.configuration.on_field_generated = original_callback
+            puts "Debug cancelled."
+            return
+          when "c", "continue"
+            Synthra.configuration.on_field_generated = original_callback
+            puts "Continuing without pausing..."
+            return
+          when "", nil
+            break
+          else
+            puts "Invalid input. Press Enter, 'q', or 'c'."
+          end
+        end
+      end
+
+      begin
+        opts = { registry: registry, mode: mode }
+        opts[:seed] = seed if seed
+        
+        result = schema.generate(**opts)
+        
+        puts
+        puts "=" * 60
+        puts "✅ Generation Complete!"
+        puts "=" * 60
+        puts
+        puts "Final Record:"
+        puts REPL::Formatter.table(result)
+      ensure
+        Synthra.configuration.on_field_generated = original_callback
+      end
+    end
+    # :nocov:
+
+    # Execute the export command
+    #
+    # Exports schema in various formats (JSON Schema, etc.)
+    #
+    # @return [Integer] exit code
+    #
+
+    def export_command
+      parse_export_options
+      schema_name = @args.shift
+
+      registry = Registry.new
+      load_schemas_from_dir_no_validate(registry, @options[:dir])
+
+      format = @options[:export_format]
+
+      # Handle "export all" mode for bulk exports
+      if @options[:all]
+        output = case format
+                 when "typescript", "ts"
+                   Export::Typescript.export_all(registry)
+                 when "javascript", "js"
+                   Export::Javascript.export_all(registry)
+                 when "python", "py", "pydantic"
+                   Export::Python.export_all(registry, style: @options[:python_style])
+                 when "dataclass"
+                   Export::Python.export_all(registry, style: :dataclass)
+                 when "sql", "sql-ddl", "postgresql", "mysql", "sqlite"
+                   Export::Sql.export_all(registry, dialect: @options[:sql_dialect])
+                 when "graphviz", "dot"
+                   Export::Graphviz.new(nil, registry: registry).export
+                 when "protobuf", "proto"
+                   Export::Protobuf.export_all(registry, package: @options[:package] || "generated")
+                 when "openapi", "swagger"
+                   Export::OpenAPI.new(registry,
+                     title: @options[:title] || "Synthra API",
+                     format: @options[:output]&.end_with?(".json") ? :json : :yaml
+                   ).export
+                 else
+                   $stderr.puts "Bulk export not supported for format: #{format}"
+                   $stderr.puts "Supported: typescript, javascript, python, sql, graphviz, protobuf, openapi"
+                   return EXIT_PARSE_ERROR
+                 end
+      else
+        unless schema_name
+          $stderr.puts "Usage: synthra export <SchemaName> [options]"
+          $stderr.puts "       synthra export --all [options]"
+          $stderr.puts ""
+          $stderr.puts "Schema formats: json-schema, typescript, javascript, sql, graphviz"
+          $stderr.puts "Data formats:   json, csv, sql-insert, yaml, xml"
+          return EXIT_PARSE_ERROR
+        end
+
+        schema = registry.schema(schema_name)
+        export_opts = build_export_options(registry)
+
+        output = case format
+                 # Schema export formats
+                 when "json-schema"
+                   Export::JsonSchema.new(schema, **export_opts).export
+                 when "typescript", "ts"
+                   Export::Typescript.new(schema, **export_opts).export
+                 when "javascript", "js"
+                   Export::Javascript.new(schema, **export_opts).export
+                 when "python", "py", "pydantic"
+                   Export::Python.new(schema, **export_opts.merge(style: @options[:python_style])).export
+                 when "dataclass"
+                   Export::Python.new(schema, **export_opts.merge(style: :dataclass)).export
+                 when "sql", "sql-ddl", "postgresql", "mysql", "sqlite"
+                   dialect = %w[postgresql mysql sqlite].include?(format) ? format.to_sym : @options[:sql_dialect]
+                   Export::Sql.new(schema, registry: registry, dialect: dialect).export
+                 when "graphviz", "dot"
+                   Export::Graphviz.new(schema, **export_opts).export
+                 when "protobuf", "proto"
+                   Export::Protobuf.new(schema, **export_opts.merge(
+                     package: @options[:package] || "generated"
+                   )).export
+                 when "openapi", "swagger"
+                   mini_registry = Registry.new
+                   mini_registry.register_schema(schema.name, schema)
+                   Export::OpenAPI.new(mini_registry,
+                     title: @options[:title] || "#{schema.name} API",
+                     format: @options[:output]&.end_with?(".json") ? :json : :yaml
+                   ).export
+
+                 # Data export formats
+                 when "json", "json-data"
+                   Export::JsonData.new(schema, **export_opts.merge(
+                     pretty: @options[:pretty],
+                     envelope: @options[:envelope]
+                   )).export
+                 when "csv"
+                   Export::Csv.new(schema, **export_opts).export
+                 when "sql-insert", "insert"
+                   Export::SqlInsert.new(schema, **export_opts.merge(
+                     dialect: @options[:sql_dialect],
+                     batch_insert: @options[:batch_insert]
+                   )).export
+                 when "yaml", "yml"
+                   Export::YamlData.new(schema, **export_opts).export
+                 when "xml"
+                   Export::XmlData.new(schema, **export_opts.merge(
+                     root: @options[:root],
+                     item: @options[:item]
+                   )).export
+                 else
+                   $stderr.puts "Unknown export format: #{format}"
+                   $stderr.puts ""
+                   $stderr.puts "Schema formats: json-schema, typescript, javascript, python, sql, graphviz, protobuf, openapi"
+                   $stderr.puts "Data formats:   json, csv, sql-insert, yaml, xml"
+                   return EXIT_PARSE_ERROR
+                 end
+      end
+
+      # Determine output path
+      output_path = if @options[:output]
+                      @options[:output]
+                    elsif @options[:auto_file]
+                      output_dir = @options[:output_dir] || "."
+                      filename = Export.auto_filename(
+                        @options[:all] ? "all_schemas" : schema_name,
+                        format
+                      )
+                      File.join(output_dir, filename)
+                    else
+                      nil
+                    end
+
+      if output_path
+        FileUtils.mkdir_p(File.dirname(output_path)) if File.dirname(output_path) != "."
+        File.write(output_path, output)
+        puts "✓ Exported to #{output_path}"
+      else
+        puts output
+      end
+
+      EXIT_SUCCESS
+    rescue KeyError
+      $stderr.puts "Unknown schema: #{schema_name}"
+      $stderr.puts "Available schemas: #{registry.names.join(", ")}"
+      EXIT_PARSE_ERROR
+    end
+
+    def build_export_options(registry)
+      {
+        registry: registry,
+        count: @options[:count],
+        seed: @options[:seed],
+        mode: @options[:mode] || :random
+      }.compact
+    end
+
+    # Export schema as JSON Schema
+    #
+    # @param schema [Schema] schema to export
+    # @param registry [Registry] registry for resolving references
+    # @return [String] JSON Schema as JSON string
+    #
+    # :nocov:
+    def export_json_schema(schema, registry)
+      json_schema = {
+        "$schema" => "https://json-schema.org/draft/2020-12/schema",
+        "$id" => "#{schema.name.downcase}.json",
+        "title" => schema.name,
+        "type" => "object",
+        "properties" => {},
+        "required" => []
+      }
+
+      schema.fields.each do |field|
+        prop = field_to_json_schema(field, registry)
+        json_schema["properties"][field.name] = prop
+        json_schema["required"] << field.name unless field.optional?
+      end
+
+      JSON.pretty_generate(json_schema)
+    end
+
+    # Convert a field to JSON Schema property
+    #
+    # @param field [Field] field to convert
+    # @param registry [Registry] registry for resolving references
+    # @return [Hash] JSON Schema property definition
+    #
+
+    def field_to_json_schema(field, registry)
+      type_name = field.type_name
+      prop = {}
+
+      case type_name
+      when "uuid", "ulid"
+        prop = { "type" => "string", "format" => "uuid" }
+      when "email"
+        prop = { "type" => "string", "format" => "email" }
+      when "url"
+        prop = { "type" => "string", "format" => "uri" }
+      when "date", "past_date", "future_date"
+        prop = { "type" => "string", "format" => "date" }
+      when "timestamp", "now"
+        prop = { "type" => "string", "format" => "date-time" }
+      when "number", "integer", "id_sequence"
+        prop = { "type" => "integer" }
+        if field.type_args[:range]
+          range = field.type_args[:range]
+          prop["minimum"] = range.min if range.respond_to?(:min)
+          prop["maximum"] = range.max if range.respond_to?(:max)
+        end
+      when "float", "money"
+        prop = { "type" => "number" }
+      when "boolean"
+        prop = { "type" => "boolean" }
+      when "text", "name", "full_name", "first_name", "last_name", "phone", "city", "country", "country_code", "postal_code"
+        prop = { "type" => "string" }
+      when "enum"
+        values = field.type_args[:values]&.map { |v| v.respond_to?(:value) ? v.value : v } || []
+        prop = { "type" => "string", "enum" => values }
+      when "const"
+        value = field.type_args[:value]
+        prop = { "const" => value }
+      when "array"
+        element_type = field.type_args[:element]
+        size = field.type_args[:size]
+        prop = { "type" => "array" }
+        if element_type && registry.schema?(element_type.to_s)
+          prop["items"] = { "$ref" => "#/$defs/#{element_type}" }
+        else
+          prop["items"] = { "type" => "string" }
+        end
+        if size.is_a?(Range)
+          prop["minItems"] = size.min
+          prop["maxItems"] = size.max
+        elsif size.is_a?(Hash)
+          prop["minItems"] = size[:min] if size[:min]
+          prop["maxItems"] = size[:max] if size[:max]
+        end
+      else
+        # Assume it's a schema reference
+        if registry.schema?(type_name)
+          prop = { "$ref" => "#/$defs/#{type_name}" }
+        else
+          prop = { "type" => "string" }
+        end
+      end
+
+      prop["nullable"] = true if field.nullable?
+      prop
+    end
+    # :nocov:
+
+    # Export schema as TypeScript interface
+    #
+    # @param schema [Schema] schema to export
+    # @param registry [Registry] registry for resolving references
+    # @return [String] TypeScript interface definition
+    #
+    # :nocov:
+    def export_typescript(schema, registry)
+      lines = ["interface #{schema.name} {"]
+      
+      schema.fields.each do |field|
+        ts_type = field_to_typescript(field, registry)
+        optional = field.optional? ? "?" : ""
+        nullable = field.nullable? ? " | null" : ""
+        lines << "  #{field.name}#{optional}: #{ts_type}#{nullable};"
+      end
+      
+      lines << "}"
+      lines.join("\n")
+    end
+
+    # Convert a field to TypeScript type
+    #
+    # @param field [Field] field to convert
+    # @param registry [Registry] registry for resolving references
+    # @return [String] TypeScript type
+    #
+
+    def field_to_typescript(field, registry)
+      type_name = field.type_name
+
+      case type_name
+      when "uuid", "ulid", "email", "url", "date", "past_date", "future_date", "timestamp", "now", "text", "name", "full_name", "first_name", "last_name", "phone", "city", "country", "country_code", "postal_code"
+        "string"
+      when "number", "integer", "id_sequence", "float", "money"
+        "number"
+      when "boolean"
+        "boolean"
+      when "enum"
+        values = field.type_args[:values]&.map { |v| "\"#{v.respond_to?(:value) ? v.value : v}\"" } || []
+        values.join(" | ")
+      when "const"
+        value = field.type_args[:value]
+        value.is_a?(String) ? "\"#{value}\"" : value.to_s
+      when "array"
+        element_type = field.type_args[:element]
+        if element_type && registry.schema?(element_type.to_s)
+          "#{element_type}[]"
+        else
+          "string[]"
+        end
+      else
+        registry.schema?(type_name) ? type_name : "any"
+      end
+    end
+    # :nocov:
+
+    # Parse options for export command
+    #
+    # @return [void]
+    #
+
+    def parse_export_options
+      @options[:export_format] = "json-schema"
+      @options[:output] = nil
+      @options[:output_dir] = nil
+      @options[:auto_file] = false
+      @options[:sql_dialect] = :postgresql
+      @options[:count] = 10
+      @options[:all] = false
+      @options[:pretty] = true
+      @options[:batch_insert] = false
+      @options[:envelope] = nil
+      @options[:root] = nil
+      @options[:item] = nil
+      @options[:python_style] = :pydantic
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: synthra export <SchemaName> [options]"
+
+        opts.on("-d", "--dir DIR", "Directory containing .dsl files") do |v|
+          @options[:dir] = v
+        end
+
+        opts.on("-f", "--format FORMAT", "Export format (see list below)") do |v|
+          @options[:export_format] = v
+        end
+
+        opts.on("-o", "--output FILE", "Output file (default: stdout)") do |v|
+          @options[:output] = v
+        end
+
+        opts.on("--out-dir DIR", "Output directory for auto-generated files") do |v|
+          @options[:output_dir] = v
+          @options[:auto_file] = true
+        end
+
+        opts.on("--auto-file", "Auto-generate filename based on schema and format") do
+          @options[:auto_file] = true
+        end
+
+        opts.on("--dialect DIALECT", "SQL dialect: postgresql, mysql, sqlite") do |v|
+          @options[:sql_dialect] = v.to_sym
+        end
+
+        opts.on("-c", "--count COUNT", Integer, "Number of records for data exports (default: 10)") do |v|
+          @options[:count] = v
+        end
+
+        opts.on("-s", "--seed SEED", Integer, "Seed for deterministic generation") do |v|
+          @options[:seed] = v
+        end
+
+        opts.on("-a", "--all", "Export all schemas (typescript/javascript/python/sql)") do
+          @options[:all] = true
+        end
+
+        opts.on("--batch", "Use batch INSERT for sql-insert format") do
+          @options[:batch_insert] = true
+        end
+
+        opts.on("--compact", "Compact output (no pretty-print)") do
+          @options[:pretty] = false
+        end
+
+        opts.on("--envelope KEY", "Wrap JSON output in envelope with this key") do |v|
+          @options[:envelope] = v
+        end
+
+        opts.on("--root NAME", "Root element name for XML") do |v|
+          @options[:root] = v
+        end
+
+        opts.on("--item NAME", "Item element name for XML") do |v|
+          @options[:item] = v
+        end
+
+        opts.on("--style STYLE", "Python style: pydantic, dataclass, typed_dict") do |v|
+          @options[:python_style] = v.to_sym
+        end
+      end.parse!(@args)
+    end
+
+    # Execute the graph command
+    #
+    # Generates GraphViz DOT output for schema visualization.
+    #
+    # @return [Integer] exit code
+    #
+
+    def graph_command
+      parse_graph_options
+      path = @args.shift || @options[:dir]
+
+      registry = Registry.new
+      if File.directory?(path)
+        load_schemas_from_dir_no_validate(registry, path)
+      else
+        registry.load_file(path, validate: false)
+      end
+
+      # Use the Export::Graphviz module
+      exporter = Export::Graphviz.new(nil, registry: registry, 
+                                       direction: @options[:direction] || "LR",
+                                       group: @options[:group])
+      dot_output = exporter.export
+
+      if @options[:output]
+        File.write(@options[:output], dot_output)
+        puts "✓ Generated graph to #{@options[:output]}"
+        
+        # Try to render PNG/SVG if graphviz is installed
+        # :nocov:
+        if @options[:render] && system("which dot > /dev/null 2>&1")
+          render_format = @options[:render_format] || "png"
+          output_file = @options[:output].sub(/\.dot$/, ".#{render_format}")
+          system("dot", "-T#{render_format}", @options[:output], "-o", output_file)
+          puts "✓ Rendered #{render_format.upcase} to #{output_file}"
+        end
+        # :nocov:
+      else
+        puts dot_output
+      end
+
+      EXIT_SUCCESS
+    end
+
+    # Generate GraphViz DOT representation of schemas
+    #
+    # @param registry [Registry] registry containing schemas
+    # @return [String] DOT format string
+    #
+    # :nocov:
+    def generate_graphviz(registry)
+      lines = [
+        "digraph Synthra {",
+        "  rankdir=LR;",
+        "  node [shape=record, fontname=\"Helvetica\"];",
+        "  edge [fontname=\"Helvetica\", fontsize=10];",
+        ""
+      ]
+
+      registry.schemas.each do |name, schema|
+        # Create node for schema
+        fields = schema.fields.map do |f|
+          optional = f.optional? ? "?" : ""
+          nullable = f.nullable? ? "?" : ""
+          "#{f.name}#{optional}: #{f.type_name}#{nullable}"
+        end
+        
+        label = "{#{name}|#{fields.join("\\l")}\\l}"
+        color = schema.deprecated? ? "gray" : "black"
+        lines << "  #{name} [label=\"#{label}\", color=#{color}];"
+      end
+
+      lines << ""
+
+      # Create edges for references
+      registry.schemas.each do |name, schema|
+        schema.fields.each do |field|
+          type_name = field.type_name
+          
+          # Direct schema reference
+          if registry.schema?(type_name)
+            lines << "  #{name} -> #{type_name} [label=\"#{field.name}\"];"
+          end
+          
+          # Array element type
+          if type_name == "array"
+            element = field.type_args[:element]
+            if element && registry.schema?(element.to_s)
+              lines << "  #{name} -> #{element} [label=\"#{field.name}[]\", style=dashed];"
+            end
+          end
+          
+          # map_by_field entries
+          if type_name == "map_by_field"
+            entries = field.type_args[:entries] || {}
+            entries.each do |entry_name, entry_info|
+              schema_name = entry_info.is_a?(Hash) ? entry_info[:schema] : entry_info.to_s
+              if schema_name && registry.schema?(schema_name)
+                lines << "  #{name} -> #{schema_name} [label=\"#{field.name}.#{entry_name}\", style=dotted];"
+              end
+            end
+          end
+        end
+      end
+
+      lines << "}"
+      lines.join("\n")
+    end
+    # :nocov:
+
+    # Parse options for graph command
+    #
+    # @return [void]
+    #
+
+    def parse_graph_options
+      @options[:output] = nil
+      @options[:render] = false
+      @options[:render_format] = "png"
+      @options[:direction] = "LR"
+      @options[:group] = false
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: synthra graph <path|directory> [options]"
+
+        opts.on("-d", "--dir DIR", "Directory containing .dsl files") do |v|
+          @options[:dir] = v
+        end
+
+        opts.on("-o", "--output FILE", "Output DOT file") do |v|
+          @options[:output] = v
+        end
+
+        opts.on("-r", "--render", "Also render image (requires graphviz)") do
+          @options[:render] = true
+        end
+
+        opts.on("--format FORMAT", "Render format: png, svg, pdf (default: png)") do |v|
+          @options[:render_format] = v
+        end
+
+        opts.on("--direction DIR", "Graph direction: LR, TB, BT, RL (default: LR)") do |v|
+          @options[:direction] = v.upcase
+        end
+
+        opts.on("-g", "--group", "Group schemas by category") do
+          @options[:group] = true
+        end
+      end.parse!(@args)
+    end
+
+    # Execute the watch command
+    #
+    # Watches for schema changes and validates on change.
+    #
+    # @return [Integer] exit code
+    #
+
+    # :nocov:
+    def watch_command
+      parse_watch_options
+      path = @args.shift || @options[:dir]
+
+      unless File.directory?(path)
+        $stderr.puts "Watch requires a directory path"
+        return EXIT_PARSE_ERROR
+      end
+
+      puts "👁  Watching #{path} for changes..."
+      puts "   Press Ctrl+C to stop"
+      puts
+
+      # Track file modification times
+      mtimes = {}
+      Dir.glob(File.join(path, "*.dsl")).each do |f|
+        mtimes[f] = File.mtime(f)
+      end
+
+      loop do
+        sleep(@options[:interval] || 1)
+
+        # Check for new or modified files
+        current_files = Dir.glob(File.join(path, "*.dsl"))
+        
+        current_files.each do |f|
+          current_mtime = File.mtime(f)
+          
+          if mtimes[f].nil?
+            puts "➕ New file: #{File.basename(f)}"
+            validate_and_report(f)
+            mtimes[f] = current_mtime
+          elsif mtimes[f] < current_mtime
+            puts "📝 Changed: #{File.basename(f)}"
+            validate_and_report(f)
+            mtimes[f] = current_mtime
+          end
+        end
+
+        # Check for deleted files
+        (mtimes.keys - current_files).each do |f|
+          puts "➖ Deleted: #{File.basename(f)}"
+          mtimes.delete(f)
+        end
+      end
+    rescue Interrupt
+      puts "\n👋 Stopped watching"
+      EXIT_SUCCESS
+    end
+    # :nocov:
+
+    # Validate a file and report results
+    #
+    # @param path [String] file path
+    # @return [void]
+    #
+    # :nocov:
+    def validate_and_report(path)
+      registry = Registry.new
+      begin
+        registry.load_file(path)
+        errors = registry.validate_paths
+        
+        if errors.empty?
+          puts "   ✓ Valid"
+        else
+          puts "   ✗ #{errors.length} error(s)"
+          errors.each { |e| puts "     - #{e.message}" }
+        end
+      rescue Synthra::Errors::ParseError => e
+        puts "   ✗ Parse error: #{e.message}"
+      end
+      puts
+    end
+    # :nocov:
+
+    # Parse options for watch command
+    #
+    # @return [void]
+    #
+    # :nocov:
+    def parse_watch_options
+      @options[:interval] = 1
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: synthra watch <directory>"
+
+        opts.on("-i", "--interval SECONDS", Integer, "Check interval in seconds") do |v|
+          @options[:interval] = v
+        end
+      end.parse!(@args)
+    end
+    # :nocov:
+
+    # Load schemas from a path (file or directory)
+    #
+    # @param registry [Registry] registry to load into
+    # @param path [String] file or directory path
+    # @return [void]
+    #
+
+    def load_path(registry, path)
+      if File.directory?(path)
+        load_schemas_from_dir_no_validate(registry, path)
+      else
+        registry.load_file(path, validate: false)
+      end
+    end
+
+    # Compare two schemas and return differences
+    #
+    # @param s1 [Schema] first schema
+    # @param s2 [Schema] second schema
+    # @return [Array<String>] list of differences
+    #
+
+    def compare_schemas(s1, s2)
+      diff = []
+
+      # Compare versions
+      # :nocov:
+      if s1.version != s2.version
+        diff << "version: #{s1.version || 'nil'} → #{s2.version || 'nil'}"
+      end
+      # :nocov:
+
+      # Compare deprecation
+      # :nocov:
+      if s1.deprecated? != s2.deprecated?
+        diff << "deprecated: #{s1.deprecated?} → #{s2.deprecated?}"
+      end
+      # :nocov:
+
+      # Compare fields
+      f1_names = s1.fields.map(&:name)
+      f2_names = s2.fields.map(&:name)
+
+      (f2_names - f1_names).each { |f| diff << "+ field: #{f}" }
+      (f1_names - f2_names).each { |f| diff << "- field: #{f}" }
+
+      # Compare field types
+      (f1_names & f2_names).each do |name|
+        field1 = s1.field(name)
+        field2 = s2.field(name)
+        if field1.type_name != field2.type_name
+          diff << "~ #{name}: #{field1.type_name} → #{field2.type_name}"
+        end
+      end
+
+      diff
+    end
+
+    # Parse options for info command
+    #
+    # @return [void]
+    #
+
+    def parse_info_options
+      @options[:verbose] = false
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: synthra info <path|directory>"
+
+        opts.on("-v", "--verbose", "Show field details") do
+          @options[:verbose] = true
+        end
+      end.parse!(@args)
+    end
+
+    # Parse options for diff command
+    #
+    # @return [void]
+    #
+
+    def parse_diff_options
+      OptionParser.new do |opts|
+        opts.banner = "Usage: synthra diff <path1> <path2>"
+      end.parse!(@args)
+    end
+
+    # Parse options for repl command
+    #
+    # @return [void]
+    #
+    # :nocov:
+    def parse_repl_options
+      @options[:verbose] = false
+      OptionParser.new do |opts|
+        opts.banner = "Usage: synthra repl [options]"
+        opts.on("-v", "--verbose", "Show verbose output including stack traces") do
+          @options[:verbose] = true
+        end
+      end.parse!(@args)
+    end
+    # :nocov:
+
+    # Load schemas from directory without validation
+    #
+    # @param registry [Registry] registry to load schemas into
+    # @param dir [String] directory path
+    # @return [void]
+    #
+
+    def load_schemas_from_dir_no_validate(registry, dir)
+      dir = File.expand_path(dir)
+      raise ArgumentError, "Invalid directory path: #{dir}" if dir.include?("..")
+      raise Errno::ENOENT, "Directory not found: #{dir}" unless Dir.exist?(dir)
+
+      pattern = File.join(dir, "*.dsl")
+      files = Dir.glob(pattern)
+
+      if files.empty?
+        $stderr.puts "No .dsl files found in #{dir}"
+        return
+      end
+
+      files.each do |f|
+        file_path = File.expand_path(f)
+        raise ArgumentError, "Invalid file path: #{f}" unless file_path.start_with?(dir)
+        registry.load_file(f, validate: false)
+      end
+    end
+
+    # Execute the generate command
+    #
+    # Loads schemas from a directory, finds the specified schema,
+    # and generates fake data according to options.
+    #
+    # @return [Integer] exit code
+    #
+
+    def generate_command
+      parse_generate_options
+      schema_name = @args.shift
+
+      unless schema_name
+        $stderr.puts "Usage: synthra generate <SchemaName> [options]"
+        return EXIT_PARSE_ERROR
+      end
+
+      registry = Registry.new
+      load_schemas_from_dir(registry, @options[:dir])
+
+      schema = registry.schema(schema_name)
+      generate_output(schema)
+      EXIT_SUCCESS
+    rescue KeyError
+      $stderr.puts "Unknown schema: #{schema_name}"
+      $stderr.puts "Available schemas: #{registry.schemas.keys.join(", ")}"
+      EXIT_PARSE_ERROR
+    end
+
+    # Load all .dsl files from a directory
+    #
+    # @param registry [Registry] registry to load schemas into
+    # @param dir [String] directory path
+    # @return [void]
+    #
+
+    def load_schemas_from_dir(registry, dir)
+
+      # Validate and sanitize directory path to prevent path traversal
+      dir = File.expand_path(dir)
+
+      # Reject paths with .. components (shouldn't happen after expand_path, but double-check)
+      # :nocov:
+      if dir.include?("..")
+        raise ArgumentError, "Invalid directory path: #{dir}"
+      end
+      # :nocov:
+
+      # Verify directory exists
+      unless Dir.exist?(dir)
+        raise Errno::ENOENT, "Directory not found: #{dir}"
+      end
+
+      pattern = File.join(dir, "*.dsl")
+      files = Dir.glob(pattern)
+
+      if files.empty?
+        $stderr.puts "No .dsl files found in #{dir}"
+        return
+      end
+
+      # Validate all files are within the directory (prevent symlink attacks)
+      files.each do |f|
+        file_path = File.expand_path(f)
+        # :nocov:
+        unless file_path.start_with?(dir)
+          raise ArgumentError, "Invalid file path: #{f}"
+        end
+        # :nocov:
+        registry.load_file(f)
+      end
+    end
+
+    # Generate and output fake data
+    #
+    # Handles both JSON and NDJSON output formats.
+    #
+    # @param schema [Schema] schema to generate from
+    # @return [void]
+    #
+
+    def generate_output(schema)
+      options = { seed: @options[:seed], mode: @options[:mode] }.compact
+
+      if @options[:format] == :ndjson
+
+        # NDJSON: One JSON object per line, streamed
+        schema.generate_stream(count: @options[:count], **options).each do |record|
+          puts JSON.generate(sanitize_for_json(record))
+        end
+      else
+
+        # JSON: Single array or object
+        records = schema.generate_many(@options[:count], **options)
+        output = @options[:count] == 1 ? records.first : records
+
+        if @options[:pretty]
+          puts JSON.pretty_generate(sanitize_for_json(output))
+        else
+          puts JSON.generate(sanitize_for_json(output))
+        end
+      end
+    end
+
+    # Sanitize values for JSON serialization
+    # Converts Infinity/NaN to null for valid JSON output
+    #
+    # @param value [Object] value to sanitize
+    # @return [Object] sanitized value
+    #
+    def sanitize_for_json(value)
+      case value
+      when Float
+        if value.infinite? || value.nan?
+          nil
+        else
+          value
+        end
+      when Hash
+        value.transform_values { |v| sanitize_for_json(v) }
+      when Array
+        value.map { |v| sanitize_for_json(v) }
+      else
+        value
+      end
+    end
+
+    # Parse options for validate command
+    #
+    # @return [void]
+    #
+
+    def parse_validate_options
+      OptionParser.new do |opts|
+        opts.banner = "Usage: synthra validate <path>"
+      end.parse!(@args)
+    end
+
+    # Parse options for lint command
+    #
+    # @return [void]
+    #
+
+    def parse_lint_options
+      @options[:verbose] = false
+      @options[:strict] = false
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: synthra lint <path|directory>"
+
+        opts.on("-v", "--verbose", "Show detailed output including schema names") do
+          @options[:verbose] = true
+        end
+
+        opts.on("--strict", "Treat warnings as errors (exit non-zero)") do
+          @options[:strict] = true
+        end
+      end.parse!(@args)
+    end
+
+    # Parse options for preview command
+    #
+    # @return [void]
+    #
+
+    def parse_preview_options
+      OptionParser.new do |opts|
+        opts.banner = "Usage: synthra preview <SchemaName> [options]"
+
+        opts.on("-d", "--dir DIR", "Directory containing .dsl files") do |v|
+          @options[:dir] = v
+        end
+
+        opts.on("-s", "--seed SEED", Integer, "Seed for deterministic generation") do |v|
+          @options[:seed] = v
+        end
+
+        opts.on("-m", "--mode MODE", %i[random edge invalid mixed], "Generation mode") do |v|
+          @options[:mode] = v
+        end
+      end.parse!(@args)
+    end
+
+    # Parse options for generate command
+    #
+    # @return [void]
+    #
+
+    def parse_generate_options
+      OptionParser.new do |opts|
+        opts.banner = "Usage: synthra generate <SchemaName> [options]"
+
+        opts.on("-d", "--dir DIR", "Directory containing .dsl files") do |v|
+          @options[:dir] = v
+        end
+
+        opts.on("-c", "--count COUNT", Integer, "Number of records to generate") do |v|
+          @options[:count] = v
+        end
+
+        opts.on("-s", "--seed SEED", Integer, "Seed for deterministic generation") do |v|
+          @options[:seed] = v
+        end
+
+        opts.on("-m", "--mode MODE", %i[random edge invalid mixed], "Generation mode") do |v|
+          @options[:mode] = v
+        end
+
+        opts.on("--json", "Output as JSON array (default)") do
+          @options[:format] = :json
+        end
+
+        opts.on("--ndjson", "Output as newline-delimited JSON") do
+          @options[:format] = :ndjson
+        end
+
+        opts.on("--pretty", "Pretty-print JSON output") do
+          @options[:pretty] = true
+        end
+      end.parse!(@args)
+    end
+
+    # Display help information
+    #
+    # @return [Integer] EXIT_SUCCESS
+    #
+
+    def show_help
+      puts <<~HELP
+        Synthra - Generate fake data from a human-friendly DSL
+
+        Usage:
+          synthra <command> [options]
+
+        Commands:
+          validate <path>         Validate a DSL schema file (syntax check)
+          lint <path|dir>         Lint schemas for semantic errors (copy paths, etc.)
+          preview <SchemaName>    Preview a single record (quick testing)
+          generate <SchemaName>   Generate fake data for a schema
+          info <path|dir>         Show schema information (version, fields, etc.)
+          diff <path1> <path2>    Compare two schema files/directories
+          export <SchemaName>     Export schema as JSON Schema or TypeScript
+          graph <path|dir>        Generate GraphViz visualization of schemas
+          watch <directory>       Watch directory for changes and validate
+          repl                    Start interactive REPL for testing
+          lsp                     Start Language Server Protocol server
+          import <file>           Import schemas from OpenAPI/Swagger
+          docs <directory>        Generate HTML documentation
+          live <directory>        Start live preview server with web UI
+          seed                    Seed database with generated data
+          server                  Start production API server
+          contracts               Manage data contracts registry
+          perf                    High-performance generation mode
+
+        Lint Options:
+          -v, --verbose           Show detailed output including schema names
+          --strict                Treat warnings as errors (exit non-zero)
+
+        Preview Options:
+          -d, --dir DIR           Directory containing .dsl files (default: .)
+          -s, --seed SEED         Seed for deterministic generation
+          -m, --mode MODE         Generation mode: random, edge, invalid, mixed
+
+        Generate Options:
+          -d, --dir DIR           Directory containing .dsl files (default: .)
+          -c, --count COUNT       Number of records to generate (default: 1)
+          -s, --seed SEED         Seed for deterministic generation
+          -m, --mode MODE         Generation mode: random, edge, invalid, mixed
+          --json                  Output as JSON array (default)
+          --ndjson                Output as newline-delimited JSON
+          --pretty                Pretty-print JSON output
+
+        Export Options:
+          -d, --dir DIR           Directory containing .dsl files
+          -f, --format FORMAT     Export format (see formats below)
+          -o, --output FILE       Output file (default: stdout)
+          --out-dir DIR           Output directory (auto-generates filename)
+          --auto-file             Auto-generate filename based on schema and format
+          -c, --count COUNT       Number of records for data exports (default: 10)
+          -s, --seed SEED         Seed for deterministic generation
+          -a, --all               Export all schemas (typescript/javascript/python/sql)
+          --dialect DIALECT       SQL dialect: postgresql, mysql, sqlite
+          --style STYLE           Python style: pydantic, dataclass, typed_dict
+          --batch                 Use batch INSERT for sql-insert format
+          --compact               No pretty-printing for JSON output
+          --envelope KEY          Wrap JSON in envelope with this key
+          --root NAME             Root element name for XML
+          --item NAME             Item element name for XML
+
+        Schema Export Formats (types/structure):
+          json-schema             JSON Schema (draft 2020-12)
+          typescript, ts          TypeScript interfaces
+          javascript, js          JavaScript with JSDoc types
+          python, py, pydantic    Python Pydantic models
+          dataclass               Python dataclasses
+          sql, sql-ddl            SQL CREATE TABLE (use --dialect)
+          graphviz, dot           GraphViz DOT diagram
+          protobuf, proto         Protocol Buffers / gRPC
+          openapi, swagger        OpenAPI 3.0 specification
+
+        Data Export Formats (generated records):
+          json, json-data         JSON array of records
+          csv                     CSV with headers
+          sql-insert, insert      SQL INSERT statements (use --dialect)
+          yaml, yml               YAML format
+          xml                     XML format (use --root, --item)
+
+        Graph Options:
+          -d, --dir DIR           Directory containing .dsl files
+          -o, --output FILE       Output DOT file
+          -r, --render            Also render image (requires graphviz installed)
+          --format FORMAT         Render format: png, svg, pdf (default: png)
+          --direction DIR         Graph direction: LR, TB, BT, RL (default: LR)
+          -g, --group             Group schemas by category
+
+        Watch Options:
+          -i, --interval SECONDS  Check interval in seconds (default: 1)
+
+        Info Options:
+          -v, --verbose           Show field details
+
+        Server Options (Production API):
+          -d, --dir DIR           Directory containing .dsl files
+          -p, --port PORT         Server port (default: 3000)
+          -h, --host HOST         Server host (default: 0.0.0.0)
+          -e, --env ENV           Environment: development, production
+          --no-cors               Disable CORS headers
+          --rate-limit LIMIT      Rate limit per minute (0 = unlimited)
+          --api-key KEY           Require API key authentication
+
+        Contracts Options:
+          -d, --dir DIR           Contracts directory (default: contracts)
+          -s, --schema-dir DIR    Schema directory
+          -v, --version VERSION   Version (semver)
+          -m, --message MSG       Changelog message
+          --sunset DATE           Sunset date for deprecation
+
+        Performance Mode Options:
+          -d, --dir DIR           Directory containing .dsl files
+          -c, --count COUNT       Number of records (default: 100000)
+          -o, --output FILE       Output file (for file generation)
+          -f, --format FORMAT     Output format: ndjson, json, csv
+          -s, --seed SEED         Random seed for deterministic generation
+          -b, --benchmark         Run benchmark instead of generating
+
+        Examples:
+          synthra validate schemas/user.dsl
+          synthra lint schemas/
+          synthra lint schemas/ --strict
+          synthra preview User --dir schemas
+          synthra generate User --dir schemas --count 10
+          synthra generate User --dir schemas --count 1000 --ndjson
+          
+          # Schema exports (types/structure)
+          synthra export User -d schemas -f json-schema
+          synthra export User -d schemas -f typescript -o user.ts
+          synthra export User -d schemas -f javascript -o user.js
+          synthra export User -d schemas -f python --style pydantic
+          synthra export User -d schemas -f dataclass -o models.py
+          synthra export User -d schemas -f sql --dialect mysql
+          synthra export --all -d schemas -f typescript -o types.ts
+          synthra export --all -d schemas -f python -o models.py
+          
+          # Auto-generate files (--auto-file or --out-dir)
+          synthra export User -d schemas -f typescript --auto-file
+          synthra export User -d schemas -f python --out-dir ./generated
+          synthra export User -d schemas -f csv -c 100 --out-dir ./data
+          
+          # Data exports (generated records)
+          synthra export User -d schemas -f json -c 100 -o users.json
+          synthra export User -d schemas -f csv -c 1000 -o users.csv
+          synthra export User -d schemas -f sql-insert -c 100 --dialect postgresql
+          synthra export User -d schemas -f sql-insert -c 1000 --batch
+          synthra export User -d schemas -f yaml -c 50 -o users.yaml
+          synthra export User -d schemas -f xml -c 20 --root users --item user
+          
+          # GraphViz visualization
+          synthra graph schemas/ --output schema.dot --render
+          synthra graph schemas/ -o schema.dot --render --format svg
+          
+          # Other commands
+          synthra watch schemas/
+          synthra info schemas/ --verbose
+          synthra diff schemas/v1/ schemas/v2/
+          synthra repl
+          synthra lsp
+          
+          # Production API Server
+          synthra server schemas/ --port 3000
+          synthra server schemas/ --port 8080 --env production
+          synthra server schemas/ --api-key secret123 --rate-limit 100
+          
+          # Data Contracts Registry
+          synthra contracts publish User -v 1.0.0 -s schemas/
+          synthra contracts deprecate User -v 1.0.0 --sunset 2026-06-01
+          synthra contracts list
+          synthra contracts history User
+          synthra contracts diff User 1.0.0 2.0.0
+          
+          # High-Performance Mode (millions of records)
+          synthra perf User -d schemas/ -c 1000000 -o users.ndjson
+          synthra perf User -d schemas/ -c 100000 -f csv -o users.csv
+          synthra perf User -d schemas/ --benchmark
+          
+          # Protocol Buffers / gRPC export
+          synthra export User -d schemas/ -f protobuf -o user.proto
+          synthra export --all -d schemas/ -f protobuf -o all.proto
+          
+          # OpenAPI export
+          synthra export --all -d schemas/ -f openapi -o api.yaml
+
+        Exit Codes:
+          0  Success
+          1  Parse/validation error
+          2  Runtime error
+      HELP
+      EXIT_SUCCESS
+    end
+
+    # Execute the LSP server command
+    #
+    # Starts the Language Server Protocol server for IDE integration.
+    # Provides features like go-to-definition, hover, completion, and diagnostics.
+    #
+    # @return [Integer] exit code (never returns normally - runs server loop)
+    #
+    # :nocov:
+    def lsp_command
+      require_relative "lsp/server"
+      server = LSP::Server.new
+      server.run
+      EXIT_SUCCESS
+    rescue Interrupt
+      EXIT_SUCCESS
+    end
+    # :nocov:
+
+    # Execute the import command
+    #
+    # Imports schemas from external formats (OpenAPI, JSON Schema).
+    #
+    # @return [Integer] exit code
+    #
+    def import_command
+      parse_import_options
+      path = @args.shift
+
+      unless path
+        $stderr.puts "Usage: synthra import <openapi.yaml|json-schema.json> [options]"
+        return EXIT_PARSE_ERROR
+      end
+
+      cmd = CLI::Commands::Import.new
+      cmd.call(path, @options)
+    end
+
+    # Execute the docs command
+    #
+    # Generates HTML documentation from schemas.
+    #
+    # @return [Integer] exit code
+    #
+    def docs_command
+      parse_docs_options
+      path = @args.shift || @options[:dir]
+
+      unless path && File.directory?(path)
+        $stderr.puts "Usage: synthra docs <schema-directory> [options]"
+        return EXIT_PARSE_ERROR
+      end
+
+      cmd = CLI::Commands::Docs.new
+      cmd.call(path, @options)
+    end
+
+    # Execute the live command
+    #
+    # Starts a live preview server with web UI.
+    #
+    # @return [Integer] exit code
+    #
+    # :nocov:
+    def live_command
+      parse_live_options
+      path = @args.shift || @options[:dir]
+
+      unless path && File.directory?(path)
+        $stderr.puts "Usage: synthra live <schema-directory> [options]"
+        return EXIT_PARSE_ERROR
+      end
+
+      cmd = CLI::Commands::Live.new
+      cmd.call(path, @options)
+    end
+    # :nocov:
+
+    # Execute the seed command
+    #
+    # Seeds databases with generated data.
+    #
+    # @return [Integer] exit code
+    #
+    def seed_command
+      parse_seed_options
+      cmd = CLI::Commands::Seed.new
+      cmd.call(@options)
+    end
+
+    # Parse options for import command
+    #
+    # @return [void]
+    #
+    def parse_import_options
+      @options[:output] = "schemas"
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: synthra import <file> [options]"
+
+        opts.on("-o", "--output DIR", "Output directory for generated schemas") do |v|
+          @options[:output] = v
+        end
+      end.parse!(@args)
+    end
+
+    # Parse options for docs command
+    #
+    # @return [void]
+    #
+    def parse_docs_options
+      @options[:output] = "docs"
+      @options[:title] = "Synthra Schema Documentation"
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: synthra docs <directory> [options]"
+
+        opts.on("-d", "--dir DIR", "Directory containing .dsl files") do |v|
+          @options[:dir] = v
+        end
+
+        opts.on("-o", "--output DIR", "Output directory for documentation") do |v|
+          @options[:output] = v
+        end
+
+        opts.on("-t", "--title TITLE", "Documentation title") do |v|
+          @options[:title] = v
+        end
+      end.parse!(@args)
+    end
+
+    # Parse options for live command
+    #
+    # @return [void]
+    #
+    # :nocov:
+    def parse_live_options
+      @options[:port] = 4567
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: synthra live <directory> [options]"
+
+        opts.on("-d", "--dir DIR", "Directory containing .dsl files") do |v|
+          @options[:dir] = v
+        end
+
+        opts.on("-p", "--port PORT", Integer, "Server port (default: 4567)") do |v|
+          @options[:port] = v
+        end
+      end.parse!(@args)
+    end
+    # :nocov:
+
+    # Parse options for seed command
+    #
+    # @return [void]
+    #
+    def parse_seed_options
+      @options[:schema_dir] = "schemas"
+      @options[:count] = 10
+      @options[:file] = nil
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: synthra seed [options]"
+
+        opts.on("-d", "--dir DIR", "Directory containing .dsl files") do |v|
+          @options[:schema_dir] = v
+        end
+
+        opts.on("-c", "--count COUNT", Integer, "Records per schema (default: 10)") do |v|
+          @options[:count] = v
+        end
+
+        opts.on("-f", "--file FILE", "Seed file to execute") do |v|
+          @options[:file] = v
+        end
+      end.parse!(@args)
+    end
+
+    # Execute the server command
+    #
+    # Starts the production API server for data generation.
+    #
+    # @return [Integer] exit code
+    #
+    # :nocov:
+    def server_command
+      parse_server_options
+      path = @args.shift || @options[:dir]
+
+      unless path && File.directory?(path)
+        $stderr.puts "Usage: synthra server <schema-directory> [options]"
+        return EXIT_PARSE_ERROR
+      end
+
+      puts "Starting Synthra API Server..."
+      Synthra::APIServer.start(
+        schema_dir: path,
+        port: @options[:port],
+        host: @options[:host],
+        environment: @options[:environment],
+        cors: @options[:cors],
+        rate_limit: @options[:rate_limit],
+        auth: @options[:auth]
+      )
+      EXIT_SUCCESS
+    rescue Interrupt
+      puts "\nServer stopped."
+      EXIT_SUCCESS
+    end
+    # :nocov:
+
+    # Execute the contracts command
+    #
+    # Manages data contracts registry.
+    #
+    # @return [Integer] exit code
+    #
+    def contracts_command
+      parse_contracts_options
+      subcommand = @args.shift
+
+      case subcommand
+      when "publish"
+        contracts_publish
+      when "deprecate"
+        contracts_deprecate
+      when "list"
+        contracts_list
+      when "history"
+        contracts_history
+      when "diff"
+        contracts_diff
+      else
+        puts "Usage: synthra contracts <subcommand> [options]"
+        puts ""
+        puts "Subcommands:"
+        puts "  publish <schema> -v VERSION   Publish a schema version"
+        puts "  deprecate <schema> -v VERSION Deprecate a schema version"
+        puts "  list                          List all contracts"
+        puts "  history <schema>              Show schema history"
+        puts "  diff <schema> <v1> <v2>       Compare versions"
+        EXIT_SUCCESS
+      end
+    end
+
+    # Execute the perf command
+    #
+    # High-performance generation for millions of records.
+    #
+    # @return [Integer] exit code
+    #
+    def perf_command
+      parse_perf_options
+      schema_name = @args.shift
+
+      unless schema_name
+        $stderr.puts "Usage: synthra perf <SchemaName> [options]"
+        return EXIT_PARSE_ERROR
+      end
+
+      registry = load_registry(@options[:dir])
+      unless registry.schema?(schema_name)
+        $stderr.puts "Schema not found: #{schema_name}"
+        return EXIT_PARSE_ERROR
+      end
+
+      schema = registry.schema(schema_name)
+      count = @options[:count]
+
+      if @options[:output]
+        # Generate to file
+        result = Synthra::PerformanceMode.to_file(
+          schema,
+          count: count,
+          output: @options[:output],
+          format: @options[:format],
+          seed: @options[:seed],
+          mode: @options[:mode]
+        ) do |progress|
+          print "\r#{progress[:current]} / #{progress[:total]} (#{progress[:percent]}%) - #{progress[:rate]} rec/s - ETA: #{progress[:eta]}s"
+        end
+        puts "\n\nGenerated #{result[:records]} records in #{result[:elapsed].round(2)}s (#{result[:rate].round(0)} rec/s)"
+      elsif @options[:benchmark]
+        # Benchmark mode
+        puts "Benchmarking #{schema_name}..."
+        results = Synthra::PerformanceMode.benchmark(schema, counts: [1000, 10_000, 100_000])
+        results.each do |c, r|
+          puts "  #{c.to_s.rjust(7)} records: #{r[:elapsed]}s (#{r[:rate]} rec/s, #{r[:memory_mb]} MB)"
+        end
+      else
+        # Stream to stdout
+        Synthra::PerformanceMode.stream(schema, count: count, seed: @options[:seed]).each do |record|
+          puts JSON.generate(record)
+        end
+      end
+
+      EXIT_SUCCESS
+    end
+
+    # Parse options for server command
+    #
+    # @return [void]
+    #
+    # :nocov:
+    def parse_server_options
+      @options[:port] = 3000
+      @options[:host] = "0.0.0.0"
+      @options[:environment] = :development
+      @options[:cors] = true
+      @options[:rate_limit] = 0
+      @options[:auth] = nil
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: synthra server <directory> [options]"
+
+        opts.on("-d", "--dir DIR", "Directory containing .dsl files") do |v|
+          @options[:dir] = v
+        end
+
+        opts.on("-p", "--port PORT", Integer, "Server port (default: 3000)") do |v|
+          @options[:port] = v
+        end
+
+        opts.on("-h", "--host HOST", "Server host (default: 0.0.0.0)") do |v|
+          @options[:host] = v
+        end
+
+        opts.on("-e", "--env ENV", "Environment: development, production") do |v|
+          @options[:environment] = v.to_sym
+        end
+
+        opts.on("--no-cors", "Disable CORS headers") do
+          @options[:cors] = false
+        end
+
+        opts.on("--rate-limit LIMIT", Integer, "Rate limit per minute (0 = unlimited)") do |v|
+          @options[:rate_limit] = v
+        end
+
+        opts.on("--api-key KEY", "Require API key authentication") do |v|
+          @options[:auth] = { type: :api_key, keys: [v] }
+        end
+      end.parse!(@args)
+    end
+    # :nocov:
+
+    # Parse options for contracts command
+    #
+    # @return [void]
+    #
+    def parse_contracts_options
+      @options[:contracts_dir] = "contracts"
+      @options[:version] = nil
+      @options[:changelog] = nil
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: synthra contracts <subcommand> [options]"
+
+        opts.on("-d", "--dir DIR", "Contracts directory (default: contracts)") do |v|
+          @options[:contracts_dir] = v
+        end
+
+        opts.on("-s", "--schema-dir DIR", "Schema directory") do |v|
+          @options[:schema_dir] = v
+        end
+
+        opts.on("-v", "--version VERSION", "Version (semver)") do |v|
+          @options[:version] = v
+        end
+
+        opts.on("-m", "--message MSG", "Changelog message") do |v|
+          @options[:changelog] = v
+        end
+
+        opts.on("--sunset DATE", "Sunset date for deprecation") do |v|
+          @options[:sunset] = Date.parse(v)
+        end
+      end.parse!(@args)
+    end
+
+    # Parse options for perf command
+    #
+    # @return [void]
+    #
+    def parse_perf_options
+      @options[:count] = 100_000
+      @options[:format] = :ndjson
+      @options[:benchmark] = false
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: synthra perf <SchemaName> [options]"
+
+        opts.on("-d", "--dir DIR", "Directory containing .dsl files") do |v|
+          @options[:dir] = v
+        end
+
+        opts.on("-c", "--count COUNT", Integer, "Number of records (default: 100000)") do |v|
+          @options[:count] = v
+        end
+
+        opts.on("-o", "--output FILE", "Output file") do |v|
+          @options[:output] = v
+        end
+
+        opts.on("-f", "--format FORMAT", "Output format: ndjson, json, csv (default: ndjson)") do |v|
+          @options[:format] = v.to_sym
+        end
+
+        opts.on("-s", "--seed SEED", Integer, "Random seed") do |v|
+          @options[:seed] = v
+        end
+
+        opts.on("-m", "--mode MODE", "Generation mode") do |v|
+          @options[:mode] = v.to_sym
+        end
+
+        opts.on("-b", "--benchmark", "Run benchmark instead of generating") do
+          @options[:benchmark] = true
+        end
+      end.parse!(@args)
+    end
+
+    # Contracts subcommand: publish
+    #
+    # @return [Integer] exit code
+    #
+    def contracts_publish
+      schema_name = @args.shift
+      version = @options[:version]
+
+      unless schema_name && version
+        $stderr.puts "Usage: synthra contracts publish <SchemaName> -v <version>"
+        return EXIT_PARSE_ERROR
+      end
+
+      registry = load_registry(@options[:schema_dir] || "schemas")
+      unless registry.schema?(schema_name)
+        $stderr.puts "Schema not found: #{schema_name}"
+        return EXIT_PARSE_ERROR
+      end
+
+      contracts = ContractsRegistry.new(@options[:contracts_dir])
+      contract = contracts.publish(
+        schema_name,
+        version: version,
+        schema: registry.schema(schema_name),
+        changelog: @options[:changelog]
+      )
+
+      puts "Published #{schema_name}@#{version}"
+      puts "  Hash: #{contract[:schema_hash]}"
+      puts "  Fields: #{contract[:fields].count}"
+      EXIT_SUCCESS
+    end
+
+    # Contracts subcommand: deprecate
+    #
+    # @return [Integer] exit code
+    #
+    def contracts_deprecate
+      schema_name = @args.shift
+      version = @options[:version]
+
+      unless schema_name && version
+        $stderr.puts "Usage: synthra contracts deprecate <SchemaName> -v <version>"
+        return EXIT_PARSE_ERROR
+      end
+
+      contracts = ContractsRegistry.new(@options[:contracts_dir])
+      contracts.deprecate(
+        schema_name,
+        version: version,
+        sunset_date: @options[:sunset],
+        message: @options[:changelog]
+      )
+
+      puts "Deprecated #{schema_name}@#{version}"
+      puts "  Sunset: #{@options[:sunset]}" if @options[:sunset]
+      EXIT_SUCCESS
+    end
+
+    # Contracts subcommand: list
+    #
+    # @return [Integer] exit code
+    #
+    def contracts_list
+      contracts = ContractsRegistry.new(@options[:contracts_dir])
+      all = contracts.list
+
+      if all.empty?
+        puts "No contracts found."
+        return EXIT_SUCCESS
+      end
+
+      puts "Data Contracts:"
+      puts ""
+
+      contracts.schema_names.each do |name|
+        puts "  #{name}:"
+        contracts.versions_for(name).each do |v|
+          contract = contracts.get(name, version: v)
+          state_icon = case contract[:state]
+                       when :published then "✅"
+                       when :deprecated then "⚠️"
+                       when :retired then "❌"
+                       else "📝"
+                       end
+          puts "    #{state_icon} v#{v} (#{contract[:fields].count} fields)"
+        end
+      end
+
+      EXIT_SUCCESS
+    end
+
+    # Contracts subcommand: history
+    #
+    # @return [Integer] exit code
+    #
+    def contracts_history
+      schema_name = @args.shift
+
+      unless schema_name
+        $stderr.puts "Usage: synthra contracts history <SchemaName>"
+        return EXIT_PARSE_ERROR
+      end
+
+      contracts = ContractsRegistry.new(@options[:contracts_dir])
+      history = contracts.history(schema_name)
+
+      if history.empty?
+        puts "No history found for #{schema_name}"
+        return EXIT_SUCCESS
+      end
+
+      puts "History for #{schema_name}:"
+      puts ""
+
+      history.reverse.each do |entry|
+        puts "  #{entry[:timestamp]} - v#{entry[:version]} #{entry[:action]}"
+        puts "    #{entry[:message]}" if entry[:message]
+      end
+
+      EXIT_SUCCESS
+    end
+
+    # Contracts subcommand: diff
+    #
+    # @return [Integer] exit code
+    #
+    def contracts_diff
+      schema_name = @args.shift
+      v1 = @args.shift
+      v2 = @args.shift
+
+      unless schema_name && v1 && v2
+        $stderr.puts "Usage: synthra contracts diff <SchemaName> <v1> <v2>"
+        return EXIT_PARSE_ERROR
+      end
+
+      contracts = ContractsRegistry.new(@options[:contracts_dir])
+      result = contracts.compatible?(schema_name, v1, v2)
+
+      puts "Comparing #{schema_name} v#{v1} → v#{v2}"
+      puts ""
+
+      if result[:compatible]
+        puts "✅ Compatible (no breaking changes)"
+      else
+        puts "❌ Breaking changes detected!"
+      end
+
+      puts ""
+      puts "Changes:"
+      changes = result[:changes]
+
+      if changes[:removed_fields].any?
+        puts "  Removed: #{changes[:removed_fields].join(', ')}"
+      end
+
+      if changes[:added_fields].any?
+        puts "  Added: #{changes[:added_fields].join(', ')}"
+      end
+
+      changes[:type_changes].each do |c|
+        puts "  Type changed: #{c[:field]} (#{c[:from]} → #{c[:to]})"
+      end
+
+      changes[:required_changes].each do |c|
+        puts "  Required changed: #{c[:field]} (#{c[:change]})"
+      end
+
+      result[:compatible] ? EXIT_SUCCESS : EXIT_PARSE_ERROR
+    end
+
+    # Load registry from directory
+    #
+    # @param dir [String] directory path
+    # @return [Registry] loaded registry
+    #
+    def load_registry(dir)
+      registry = Registry.new
+      registry.load_dir(dir || ".")
+      registry
+    end
+
+    # Display version information
+    #
+    # @return [Integer] EXIT_SUCCESS
+    #
+
+    def show_version
+      puts "Synthra version #{Synthra::VERSION}"
+      EXIT_SUCCESS
+    end
+  end
+end