synthra 0.1.0

data/lib/synthra/export/javascript.rb

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Synthra
+  module Export
+    # Exports schema as JavaScript with JSDoc type annotations
+    #
+    # @example Export a schema
+    #   exporter = Javascript.new(schema, registry: registry)
+    #   javascript = exporter.export
+    #
+    class Javascript < Base
+      # Type mappings from DSL types to JSDoc types
+      TYPE_MAPPINGS = {
+        # Strings
+        "uuid" => "string",
+        "ulid" => "string",
+        "email" => "string",
+        "url" => "string",
+        "ip" => "string",
+        "ipv6" => "string",
+        "date" => "string",
+        "past_date" => "string",
+        "future_date" => "string",
+        "timestamp" => "string",
+        "text" => "string",
+        "name" => "string",
+        "full_name" => "string",
+        "first_name" => "string",
+        "last_name" => "string",
+        "phone" => "string",
+        "city" => "string",
+        "country" => "string",
+        "country_code" => "string",
+        "postal_code" => "string",
+        "state" => "string",
+        "street" => "string",
+        "address" => "string",
+        "username" => "string",
+        "social_handle" => "string",
+        "domain" => "string",
+        "user_agent" => "string",
+        "mac_address" => "string",
+        "iban" => "string",
+        "credit_card" => "string",
+        "currency" => "string",
+        "currency_code" => "string",
+        "paragraph" => "string",
+        "sentence" => "string",
+        "word" => "string",
+        "message_text" => "string",
+        "hashtag_text" => "string",
+        "snowflake_id" => "string",
+        "numeric_string_id" => "string",
+
+        # Numbers (integers + floats both map to JS number)
+        "number" => "number",
+        "integer" => "number",
+        "age" => "number",
+        "airport_elevation" => "number",
+        "discount" => "number",
+        "formula" => "number",
+        "row_number" => "number",
+        "sequence" => "number",
+        "id_sequence" => "number",
+        "float" => "number",
+        "money" => "number",
+        "latitude" => "number",
+        "longitude" => "number",
+        "airport_latitude" => "number",
+        "airport_longitude" => "number",
+        "product_price" => "number",
+        "tax_rate" => "number",
+        "transaction_amount" => "number",
+
+        # Boolean
+        "boolean" => "boolean",
+
+        # Date (string in JSON)
+        "date_between" => "string",
+        "mobile_device_release_date" => "string",
+        "now" => "string",
+        "datetime" => "string",
+
+        # Objects
+        "object" => "Object",
+        "map_by_field" => "Object",
+
+        # Arrays
+        "array" => "Array",
+        "empty_array" => "Array",
+        "json_array" => "Array",
+        "indices_pair" => "Array.<number>"
+      }.freeze
+
+      def export
+        lines = []
+
+        # Add header comment
+        lines << "/**"
+        lines << " * Generated from Synthra schema: #{schema.name}"
+        lines << " * Version: #{schema.version}" if schema.version
+        lines << " * @deprecated #{schema.deprecation_message}" if schema.deprecated?
+        lines << " */"
+        lines << ""
+
+        # Export referenced schemas first
+        exported = Set.new
+        collect_referenced_schemas.each do |ref_schema|
+          lines << build_typedef(ref_schema)
+          lines << ""
+          exported << ref_schema.name
+        end
+
+        # Export main schema
+        lines << build_typedef(schema) unless exported.include?(schema.name)
+
+        # Add factory function
+        lines << ""
+        lines << build_factory_function(schema)
+
+        lines.join("\n")
+      end
+
+      # Export all schemas in a registry
+      #
+      # @param registry [Registry] the registry
+      # @param options [Hash] export options
+      # @return [String] JavaScript with JSDoc types
+      #
+      def self.export_all(registry, **options)
+        lines = []
+        lines << "/**"
+        lines << " * Generated from Synthra schemas"
+        lines << " * Schemas: #{registry.names.join(', ')}"
+        lines << " */"
+        lines << ""
+
+        registry.schemas.each do |name, schema|
+          exporter = new(schema, registry: registry, **options)
+          lines << exporter.build_typedef(schema)
+          lines << ""
+        end
+
+        lines.join("\n")
+      end
+
+      def build_typedef(target_schema)
+        lines = []
+
+        # JSDoc typedef
+        lines << "/**"
+        lines << " * @typedef {Object} #{target_schema.name}"
+        if target_schema.deprecated?
+          lines << " * @deprecated #{target_schema.deprecation_message || 'This type is deprecated'}"
+        end
+
+        target_schema.fields.each do |field|
+          js_type = field_to_javascript(field)
+          optional = field.optional? ? " (optional)" : ""
+          nullable = field.nullable? ? "|null" : ""
+
+          lines << " * @property {#{js_type}#{nullable}} #{field.optional? ? "[#{field.name}]" : field.name}#{optional}"
+        end
+
+        lines << " */"
+        lines.join("\n")
+      end
+
+      private
+
+      def collect_referenced_schemas
+        schemas = []
+        schema.fields.each do |field|
+          collect_field_schemas(field, schemas)
+        end
+        schemas.uniq(&:name)
+      end
+
+      def collect_field_schemas(field, schemas)
+        type_name = field.type_name
+
+        if schema_reference?(type_name)
+          ref_schema = get_schema(type_name)
+          if ref_schema && !schemas.any? { |s| s.name == ref_schema.name }
+            schemas << ref_schema
+            ref_schema.fields.each { |f| collect_field_schemas(f, schemas) }
+          end
+        end
+
+        if type_name == "array"
+          element = field.type_args[:element]
+          if element && schema_reference?(element.to_s)
+            ref_schema = get_schema(element.to_s)
+            if ref_schema && !schemas.any? { |s| s.name == ref_schema.name }
+              schemas << ref_schema
+              ref_schema.fields.each { |f| collect_field_schemas(f, schemas) }
+            end
+          end
+        end
+      end
+
+      def field_to_javascript(field)
+        type_name = field.type_name
+        type_args = field.type_args
+
+        case type_name
+        when "enum"
+          build_enum_type(type_args)
+        when "const"
+          build_const_type(type_args)
+        when "array"
+          build_array_type(type_args)
+        when "one_of"
+          build_one_of_type(type_args)
+        when "map_by_field"
+          "Object.<string, Object>"
+        else
+          if TYPE_MAPPINGS[type_name]
+            TYPE_MAPPINGS[type_name]
+          elsif schema_reference?(type_name)
+            type_name
+          else
+            # Most Synthra types generate strings, so an unmapped, non-structural
+            # type is a string rather than the any-type wildcard.
+            "string"
+          end
+        end
+      end
+
+      def build_enum_type(args)
+        values = args[:values]&.map { |v| v.respond_to?(:value) ? v.value : v } || []
+        "(#{values.map { |v| "'#{v}'" }.join('|')})"
+      end
+
+      def build_const_type(args)
+        value = args[:value]
+        case value
+        when String
+          "'#{value}'"
+        when TrueClass, FalseClass
+          value.to_s
+        when Numeric
+          value.to_s
+        else
+          "'#{value}'"
+        end
+      end
+
+      def build_array_type(args)
+        element = args[:element]
+        if element
+          if schema_reference?(element.to_s)
+            "Array.<#{element}>"
+          elsif TYPE_MAPPINGS[element.to_s]
+            "Array.<#{TYPE_MAPPINGS[element.to_s]}>"
+          else
+            # Unknown element types are string-producing types (e.g. array(string)).
+            "Array.<string>"
+          end
+        else
+          "Array.<*>"
+        end
+      end
+
+      def build_one_of_type(args)
+        schemas = args[:schemas] || []
+        types = schemas.map do |s|
+          schema_name = s.is_a?(Hash) ? (s[:schema] || s["schema"]) : s.to_s
+          schema_reference?(schema_name) ? schema_name : "Object"
+        end
+        "(#{types.join('|')})"
+      end
+
+      def build_factory_function(target_schema)
+        lines = []
+        lines << "/**"
+        lines << " * Create a new #{target_schema.name} object"
+        lines << " * @param {Partial<#{target_schema.name}>} [overrides] - Optional field overrides"
+        lines << " * @returns {#{target_schema.name}}"
+        lines << " */"
+        lines << "function create#{target_schema.name}(overrides = {}) {"
+        lines << "  return {"
+
+        target_schema.fields.each_with_index do |field, i|
+          default = field_default_value(field)
+          comma = i < target_schema.fields.length - 1 ? "," : ""
+          lines << "    #{field.name}: overrides.#{field.name} ?? #{default}#{comma}"
+        end
+
+        lines << "  };"
+        lines << "}"
+        lines.join("\n")
+      end
+
+      def field_default_value(field)
+        type_name = field.type_name
+
+        return "null" if field.optional? || field.nullable?
+
+        case type_name
+        when "uuid", "ulid", "text", "name", "email", "url", "phone", "city", "country", "address"
+          "''"
+        when "number", "integer", "float", "money", "id_sequence"
+          "0"
+        when "boolean"
+          "false"
+        when "array"
+          "[]"
+        when "object", "map_by_field"
+          "{}"
+        when "enum"
+          values = field.type_args[:values] || []
+          values.first ? "'#{values.first.respond_to?(:value) ? values.first.value : values.first}'" : "''"
+        when "const"
+          value = field.type_args[:value]
+          value.is_a?(String) ? "'#{value}'" : value.to_s
+        when "timestamp", "now", "date", "past_date", "future_date"
+          "new Date().toISOString()"
+        else
+          schema_reference?(type_name) ? "{}" : "null"
+        end
+      end
+    end
+    # :nocov:
+  end
+end

data/lib/synthra/export/json_data.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Synthra
+  module Export
+    # Exports generated data as JSON
+    #
+    # @example Export schema data as JSON
+    #   exporter = JsonData.new(schema, registry: registry, count: 100)
+    #   json = exporter.export
+    #
+    class JsonData < Base
+      def export
+        count = options[:count] || 10
+        seed = options[:seed]
+        mode = options[:mode] || :random
+        pretty = options[:pretty] != false
+
+        records = if count == 1
+                    [schema.generate(seed: seed, mode: mode, registry: registry)]
+                  else
+                    schema.generate_many(count, seed: seed, mode: mode, registry: registry)
+                  end
+
+        if pretty
+          JSON.pretty_generate(wrap_output(records))
+        else
+          JSON.generate(wrap_output(records))
+        end
+      end
+
+      private
+
+      def wrap_output(records)
+        # :nocov:
+        if options[:wrap] == false
+          records
+        # :nocov:
+        elsif options[:envelope]
+          {
+            options[:envelope] => records,
+            "meta" => build_meta(records)
+          }
+        else
+          records
+        end
+      end
+
+      def build_meta(records)
+        {
+          "schema" => schema.name,
+          "version" => schema.version,
+          "count" => records.is_a?(Array) ? records.length : 1,
+          "generated_at" => Time.now.iso8601,
+          "seed" => options[:seed]
+        }.compact
+      end
+    end
+    # :nocov:
+  end
+end

data/lib/synthra/export/json_schema.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Synthra
+  module Export
+    # Exports schema as JSON Schema (draft 2020-12)
+    #
+    # @example Export a schema
+    #   exporter = JsonSchema.new(schema, registry: registry)
+    #   json_schema = exporter.export
+    #
+    class JsonSchema < Base
+      # JSON Schema draft version
+      SCHEMA_VERSION = "https://json-schema.org/draft/2020-12/schema"
+
+      # Type mappings from DSL types to JSON Schema types
+      TYPE_MAPPINGS = {
+        # Strings with formats
+        "uuid" => { "type" => "string", "format" => "uuid" },
+        "ulid" => { "type" => "string", "pattern" => "^[0-7][0-9A-HJKMNP-TV-Z]{25}$" },
+        "email" => { "type" => "string", "format" => "email" },
+        "url" => { "type" => "string", "format" => "uri" },
+        "ip" => { "type" => "string", "format" => "ipv4" },
+        "ipv6" => { "type" => "string", "format" => "ipv6" },
+        "date" => { "type" => "string", "format" => "date" },
+        "date_between" => { "type" => "string", "format" => "date" },
+        "past_date" => { "type" => "string", "format" => "date" },
+        "future_date" => { "type" => "string", "format" => "date" },
+        "mobile_device_release_date" => { "type" => "string", "format" => "date" },
+        "now" => { "type" => "string", "format" => "date" },
+        "timestamp" => { "type" => "string", "format" => "date-time" },
+        "datetime" => { "type" => "string", "format" => "date-time" },
+
+        # Plain strings
+        "text" => { "type" => "string" },
+        "name" => { "type" => "string" },
+        "full_name" => { "type" => "string" },
+        "first_name" => { "type" => "string" },
+        "last_name" => { "type" => "string" },
+        "phone" => { "type" => "string" },
+        "city" => { "type" => "string" },
+        "country" => { "type" => "string" },
+        "country_code" => { "type" => "string", "minLength" => 2, "maxLength" => 3 },
+        "postal_code" => { "type" => "string" },
+        "state" => { "type" => "string" },
+        "street" => { "type" => "string" },
+        "address" => { "type" => "string" },
+        "username" => { "type" => "string" },
+        "social_handle" => { "type" => "string" },
+        "domain" => { "type" => "string", "format" => "hostname" },
+        "user_agent" => { "type" => "string" },
+        "mac_address" => { "type" => "string" },
+        "iban" => { "type" => "string" },
+        "credit_card" => { "type" => "string" },
+        "currency" => { "type" => "string" },
+        "currency_code" => { "type" => "string", "minLength" => 3, "maxLength" => 3 },
+        "paragraph" => { "type" => "string" },
+        "sentence" => { "type" => "string" },
+        "word" => { "type" => "string" },
+        "message_text" => { "type" => "string" },
+        "hashtag_text" => { "type" => "string" },
+
+        # Numbers (integers)
+        "number" => { "type" => "integer" },
+        "integer" => { "type" => "integer" },
+        "age" => { "type" => "integer", "minimum" => 0, "maximum" => 150 },
+        "airport_elevation" => { "type" => "integer" },
+        "discount" => { "type" => "integer" },
+        "formula" => { "type" => "integer" },
+        "row_number" => { "type" => "integer" },
+        "sequence" => { "type" => "integer" },
+        "id_sequence" => { "type" => "integer" },
+
+        # Numbers (floats)
+        "float" => { "type" => "number" },
+        "money" => { "type" => "number" },
+        "latitude" => { "type" => "number", "minimum" => -90, "maximum" => 90 },
+        "longitude" => { "type" => "number", "minimum" => -180, "maximum" => 180 },
+        "airport_latitude" => { "type" => "number", "minimum" => -90, "maximum" => 90 },
+        "airport_longitude" => { "type" => "number", "minimum" => -180, "maximum" => 180 },
+        "product_price" => { "type" => "number" },
+        "tax_rate" => { "type" => "number" },
+        "transaction_amount" => { "type" => "number" },
+
+        # Numeric-looking strings
+        "snowflake_id" => { "type" => "string", "pattern" => "^[0-9]+$" },
+        "numeric_string_id" => { "type" => "string", "pattern" => "^[0-9]+$" },
+
+        # Boolean
+        "boolean" => { "type" => "boolean" },
+
+        # Objects
+        "object" => { "type" => "object" },
+        "map_by_field" => { "type" => "object" },
+
+        # Arrays
+        "array" => { "type" => "array" },
+        "empty_array" => { "type" => "array", "maxItems" => 0 },
+        "json_array" => { "type" => "array" },
+        "indices_pair" => { "type" => "array", "items" => { "type" => "integer" }, "minItems" => 2, "maxItems" => 2 }
+      }.freeze
+
+      def export
+        json_schema = build_root_schema
+        JSON.pretty_generate(json_schema)
+      end
+
+      private
+
+      def build_root_schema
+        result = {
+          "$schema" => SCHEMA_VERSION,
+          "$id" => "#{schema.name.downcase}.json",
+          "title" => schema.name,
+          "description" => build_description,
+          "type" => "object",
+          "properties" => {},
+          "required" => []
+        }
+
+        # Add $defs for referenced schemas
+        defs = build_definitions
+        result["$defs"] = defs unless defs.empty?
+
+        # Add properties
+        schema.fields.each do |field|
+          result["properties"][field.name] = field_to_schema(field)
+          result["required"] << field.name unless field.optional?
+        end
+
+        result
+      end
+
+      def build_description
+        parts = ["Generated from Synthra schema: #{schema.name}"]
+        parts << "Version: #{schema.version}" if schema.version
+        parts << "DEPRECATED: #{schema.deprecation_message}" if schema.deprecated?
+        parts.join(". ")
+      end
+
+      def build_definitions
+        defs = {}
+        collect_referenced_schemas.each do |ref_schema|
+          defs[ref_schema.name] = build_schema_definition(ref_schema)
+        end
+        defs
+      end
+
+      def collect_referenced_schemas
+        schemas = []
+        schema.fields.each do |field|
+          collect_field_schemas(field, schemas)
+        end
+        schemas.uniq(&:name)
+      end
+
+      def collect_field_schemas(field, schemas)
+        type_name = field.type_name
+
+        if schema_reference?(type_name)
+          ref_schema = get_schema(type_name)
+          schemas << ref_schema if ref_schema && !schemas.any? { |s| s.name == ref_schema.name }
+        end
+
+        if type_name == "array"
+          element = field.type_args[:element]
+          if element && schema_reference?(element.to_s)
+            ref_schema = get_schema(element.to_s)
+            schemas << ref_schema if ref_schema && !schemas.any? { |s| s.name == ref_schema.name }
+          end
+        end
+      end
+
+      def build_schema_definition(ref_schema)
+        result = {
+          "type" => "object",
+          "properties" => {},
+          "required" => []
+        }
+
+        ref_schema.fields.each do |field|
+          result["properties"][field.name] = field_to_schema(field)
+          result["required"] << field.name unless field.optional?
+        end
+
+        result
+      end
+
+      def field_to_schema(field)
+        type_name = field.type_name
+        type_args = field.type_args
+
+        prop = case type_name
+               when "enum"
+                 build_enum_schema(type_args)
+               when "const"
+                 build_const_schema(type_args)
+               when "array"
+                 build_array_schema(type_args)
+               when "one_of"
+                 build_one_of_schema(type_args)
+               when "map_by_field"
+                 build_map_by_field_schema(type_args)
+               else
+                 if TYPE_MAPPINGS[type_name]
+                   TYPE_MAPPINGS[type_name].dup
+                 elsif schema_reference?(type_name)
+                   { "$ref" => "#/$defs/#{type_name}" }
+                 else
+                   { "type" => "string" }
+                 end
+               end
+
+        # Add range constraints
+        if type_args[:range] && prop["type"] == "integer"
+          range = type_args[:range]
+          prop["minimum"] = range.min if range.respond_to?(:min)
+          prop["maximum"] = range.max if range.respond_to?(:max)
+        end
+
+        # Handle nullable
+        if field.nullable?
+          prop = { "oneOf" => [prop, { "type" => "null" }] }
+        end
+
+        prop
+      end
+
+      def build_enum_schema(args)
+        values = args[:values]&.map { |v| v.respond_to?(:value) ? v.value : v } || []
+        { "type" => "string", "enum" => values }
+      end
+
+      def build_const_schema(args)
+        { "const" => args[:value] }
+      end
+
+      def build_array_schema(args)
+        element = args[:element]
+        size = args[:size]
+
+        prop = { "type" => "array" }
+
+        if element
+          if schema_reference?(element.to_s)
+            prop["items"] = { "$ref" => "#/$defs/#{element}" }
+          elsif TYPE_MAPPINGS[element.to_s]
+            prop["items"] = TYPE_MAPPINGS[element.to_s].dup
+          else
+            prop["items"] = { "type" => "string" }
+          end
+        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]
+        elsif size.is_a?(Integer)
+          prop["minItems"] = size
+          prop["maxItems"] = size
+        end
+
+        prop
+      end
+
+      def build_one_of_schema(args)
+        schemas = args[:schemas] || []
+        one_of = schemas.map do |s|
+          schema_name = s.is_a?(Hash) ? (s[:schema] || s["schema"]) : s.to_s
+          if schema_reference?(schema_name)
+            { "$ref" => "#/$defs/#{schema_name}" }
+          else
+            { "type" => "object" }
+          end
+        end
+        { "oneOf" => one_of }
+      end
+
+      def build_map_by_field_schema(args)
+        {
+          "type" => "object",
+          "additionalProperties" => { "type" => "object" }
+        }
+      end
+    end
+    # :nocov:
+  end
+end