synthra 0.1.0

data/lib/synthra/export/type_mapping.rb

@@ -0,0 +1,389 @@
+# frozen_string_literal: true
+
+module Synthra
+  module Export
+    # Shared type mapping for all export formats
+    #
+    # This module provides consistent type mapping across all exporters,
+    # reducing code duplication and ensuring consistency.
+    #
+    # rubocop:disable Metrics/ModuleLength -- this is a set of large lookup tables, not logic.
+    module TypeMapping
+      # Map Synthra types to JSON Schema types
+      JSON_SCHEMA_TYPES = {
+        # Identifiers
+        "uuid" => { "type" => "string", "format" => "uuid" },
+        "ulid" => { "type" => "string", "pattern" => "^[0-9A-Z]{26}$" },
+        "id_sequence" => { "type" => "integer" },
+        "snowflake_id" => { "type" => "string" },
+        "numeric_string_id" => { "type" => "string", "pattern" => "^[0-9]+$" },
+
+        # Strings
+        "text" => { "type" => "string" },
+        "name" => { "type" => "string" },
+        "first_name" => { "type" => "string" },
+        "last_name" => { "type" => "string" },
+        "full_name" => { "type" => "string" },
+        "username" => { "type" => "string" },
+        "email" => { "type" => "string", "format" => "email" },
+        "phone" => { "type" => "string" },
+        "url" => { "type" => "string", "format" => "uri" },
+        "domain" => { "type" => "string", "format" => "hostname" },
+        "ip" => { "type" => "string", "format" => "ipv4" },
+        "ipv6" => { "type" => "string", "format" => "ipv6" },
+        "address" => { "type" => "string" },
+        "city" => { "type" => "string" },
+        "state" => { "type" => "string" },
+        "country" => { "type" => "string" },
+        "country_code" => { "type" => "string" },
+        "postal_code" => { "type" => "string" },
+        "password" => { "type" => "string" },
+        "color" => { "type" => "string" },
+        "hex_color" => { "type" => "string", "pattern" => "^#[0-9a-fA-F]{6}$" },
+        "user_agent" => { "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" },
+
+        # 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" },
+
+        # Boolean
+        "boolean" => { "type" => "boolean" },
+
+        # Date
+        "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" },
+
+        # Date/Time
+        "timestamp" => { "type" => "string", "format" => "date-time" },
+        "datetime" => { "type" => "string", "format" => "date-time" },
+        "time" => { "type" => "string", "format" => "time" },
+
+        # Structural
+        "object" => { "type" => "object" },
+        "map_by_field" => { "type" => "object" },
+        "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
+
+      # Map Synthra types to TypeScript types
+      TYPESCRIPT_TYPES = {
+        # Identifiers
+        "uuid" => "string",
+        "ulid" => "string",
+        "id_sequence" => "number",
+        "snowflake_id" => "string",
+        "numeric_string_id" => "string",
+
+        # Strings
+        "text" => "string",
+        "name" => "string",
+        "first_name" => "string",
+        "last_name" => "string",
+        "full_name" => "string",
+        "username" => "string",
+        "email" => "string",
+        "phone" => "string",
+        "url" => "string",
+        "domain" => "string",
+        "ip" => "string",
+        "ipv6" => "string",
+        "address" => "string",
+        "city" => "string",
+        "state" => "string",
+        "country" => "string",
+        "country_code" => "string",
+        "postal_code" => "string",
+        "password" => "string",
+        "color" => "string",
+        "hex_color" => "string",
+        "user_agent" => "string",
+        "mac_address" => "string",
+
+        # Numbers (integers + floats both map to TS number)
+        "number" => "number",
+        "integer" => "number",
+        "age" => "number",
+        "airport_elevation" => "number",
+        "discount" => "number",
+        "formula" => "number",
+        "row_number" => "number",
+        "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/Time (string in JSON)
+        "date" => "string",
+        "date_between" => "string",
+        "past_date" => "string",
+        "future_date" => "string",
+        "mobile_device_release_date" => "string",
+        "now" => "string",
+        "timestamp" => "string",
+        "datetime" => "string",
+        "time" => "string",
+
+        # Structural
+        "object" => "Record<string, unknown>",
+        "map_by_field" => "Record<string, unknown>",
+        "array" => "unknown[]",
+        "empty_array" => "never[]",
+        "json_array" => "unknown[]",
+        "indices_pair" => "[number, number]"
+      }.freeze
+
+      # Map Synthra types to Python types
+      PYTHON_TYPES = {
+        # Identifiers
+        "uuid" => "UUID",
+        "ulid" => "str",
+        "id_sequence" => "int",
+        "snowflake_id" => "str",
+        "numeric_string_id" => "str",
+
+        # Strings
+        "text" => "str",
+        "name" => "str",
+        "first_name" => "str",
+        "last_name" => "str",
+        "full_name" => "str",
+        "username" => "str",
+        "email" => "EmailStr",
+        "phone" => "str",
+        "url" => "HttpUrl",
+        "domain" => "str",
+        "ip" => "IPv4Address",
+        "ipv6" => "IPv6Address",
+        "address" => "str",
+        "city" => "str",
+        "state" => "str",
+        "country" => "str",
+        "country_code" => "str",
+        "postal_code" => "str",
+        "password" => "str",
+        "color" => "str",
+        "hex_color" => "str",
+        "user_agent" => "str",
+        "mac_address" => "str",
+
+        # Numbers (integers)
+        "number" => "int",
+        "integer" => "int",
+        "age" => "int",
+        "airport_elevation" => "int",
+        "discount" => "int",
+        "formula" => "int",
+        "row_number" => "int",
+        "sequence" => "int",
+
+        # Numbers (floats)
+        "float" => "float",
+        "money" => "Decimal",
+        "latitude" => "float",
+        "longitude" => "float",
+        "airport_latitude" => "float",
+        "airport_longitude" => "float",
+        "product_price" => "float",
+        "tax_rate" => "float",
+        "transaction_amount" => "float",
+
+        # Boolean
+        "boolean" => "bool",
+
+        # Date
+        "date" => "date",
+        "date_between" => "date",
+        "past_date" => "date",
+        "future_date" => "date",
+        "mobile_device_release_date" => "date",
+        "now" => "date",
+
+        # Date/Time
+        "timestamp" => "datetime",
+        "datetime" => "datetime",
+        "time" => "time",
+
+        # Structural
+        "object" => "Dict[str, Any]",
+        "map_by_field" => "Dict[str, Any]",
+        "array" => "List[Any]",
+        "empty_array" => "List[Any]",
+        "json_array" => "List[Any]",
+        "indices_pair" => "Tuple[int, int]"
+      }.freeze
+
+      # Map Synthra types to SQL types
+      SQL_TYPES = {
+        postgresql: {
+          "uuid" => "UUID",
+          "ulid" => "VARCHAR(26)",
+          "id_sequence" => "SERIAL",
+          "snowflake_id" => "BIGINT",
+          "numeric_string_id" => "VARCHAR(20)",
+          "text" => "TEXT",
+          "name" => "VARCHAR(255)",
+          "first_name" => "VARCHAR(100)",
+          "last_name" => "VARCHAR(100)",
+          "full_name" => "VARCHAR(255)",
+          "username" => "VARCHAR(100)",
+          "email" => "VARCHAR(255)",
+          "phone" => "VARCHAR(20)",
+          "url" => "TEXT",
+          "domain" => "VARCHAR(255)",
+          "ip" => "INET",
+          "ipv6" => "INET",
+          "address" => "TEXT",
+          "city" => "VARCHAR(100)",
+          "state" => "VARCHAR(100)",
+          "country" => "VARCHAR(100)",
+          "country_code" => "CHAR(2)",
+          "postal_code" => "VARCHAR(20)",
+          "password" => "VARCHAR(255)",
+          "color" => "VARCHAR(50)",
+          "hex_color" => "CHAR(7)",
+          "number" => "INTEGER",
+          "integer" => "INTEGER",
+          "age" => "INTEGER",
+          "airport_elevation" => "INTEGER",
+          "discount" => "INTEGER",
+          "formula" => "INTEGER",
+          "row_number" => "INTEGER",
+          "sequence" => "INTEGER",
+          "float" => "REAL",
+          "money" => "DECIMAL(10, 2)",
+          "latitude" => "DECIMAL(10, 8)",
+          "longitude" => "DECIMAL(11, 8)",
+          "airport_latitude" => "DECIMAL(10, 8)",
+          "airport_longitude" => "DECIMAL(11, 8)",
+          "product_price" => "DECIMAL(10, 2)",
+          "tax_rate" => "DECIMAL(10, 4)",
+          "transaction_amount" => "DECIMAL(15, 2)",
+          "boolean" => "BOOLEAN",
+          "date" => "DATE",
+          "date_between" => "DATE",
+          "past_date" => "DATE",
+          "future_date" => "DATE",
+          "mobile_device_release_date" => "DATE",
+          "now" => "DATE",
+          "timestamp" => "TIMESTAMP",
+          "datetime" => "TIMESTAMP",
+          "time" => "TIME",
+          "object" => "JSONB",
+          "map_by_field" => "JSONB",
+          "array" => "JSONB",
+          "empty_array" => "JSONB",
+          "json_array" => "JSONB",
+          "indices_pair" => "INTEGER[]"
+        },
+        mysql: {
+          "uuid" => "CHAR(36)",
+          "ulid" => "CHAR(26)",
+          "id_sequence" => "INT AUTO_INCREMENT",
+          "snowflake_id" => "BIGINT",
+          "numeric_string_id" => "VARCHAR(20)",
+          "text" => "TEXT",
+          "name" => "VARCHAR(255)",
+          "email" => "VARCHAR(255)",
+          "number" => "INT",
+          "integer" => "INT",
+          "float" => "FLOAT",
+          "money" => "DECIMAL(10, 2)",
+          "boolean" => "TINYINT(1)",
+          "date" => "DATE",
+          "timestamp" => "DATETIME",
+          "datetime" => "DATETIME"
+        },
+        sqlite: {
+          "uuid" => "TEXT",
+          "ulid" => "TEXT",
+          "id_sequence" => "INTEGER PRIMARY KEY AUTOINCREMENT",
+          "text" => "TEXT",
+          "name" => "TEXT",
+          "email" => "TEXT",
+          "number" => "INTEGER",
+          "integer" => "INTEGER",
+          "float" => "REAL",
+          "money" => "REAL",
+          "boolean" => "INTEGER",
+          "date" => "TEXT",
+          "timestamp" => "TEXT"
+        }
+      }.freeze
+
+      # Get JSON Schema type for a Synthra type
+      #
+      # @param type_name [String] the type name
+      # @return [Hash] JSON Schema type definition
+      #
+      def json_schema_type(type_name)
+        JSON_SCHEMA_TYPES[type_name] || { "type" => "string" }
+      end
+
+      # Get TypeScript type for a Synthra type
+      #
+      # @param type_name [String] the type name
+      # @return [String] TypeScript type
+      #
+      def typescript_type(type_name)
+        # Default to the language's string type: the overwhelming majority of
+        # Synthra types generate strings, so an unmapped type is a string.
+        TYPESCRIPT_TYPES[type_name] || "string"
+      end
+
+      # Get Python type for a Synthra type
+      #
+      # @param type_name [String] the type name
+      # @return [String] Python type
+      #
+      def python_type(type_name)
+        # Default to the language's string type: the overwhelming majority of
+        # Synthra types generate strings, so an unmapped type is a string.
+        PYTHON_TYPES[type_name] || "str"
+      end
+
+      # Get SQL type for a Synthra type
+      #
+      # @param type_name [String] the type name
+      # @param dialect [Symbol] SQL dialect (:postgresql, :mysql, :sqlite)
+      # @return [String] SQL type
+      #
+      def sql_type(type_name, dialect: :postgresql)
+        dialect_types = SQL_TYPES[dialect] || SQL_TYPES[:postgresql]
+        dialect_types[type_name] || "VARCHAR(255)"
+      end
+    end
+    # rubocop:enable Metrics/ModuleLength
+  end
+end

data/lib/synthra/export/typescript.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Synthra
+  module Export
+    # Exports schema as TypeScript interfaces
+    #
+    # @example Export a schema
+    #   exporter = Typescript.new(schema, registry: registry)
+    #   typescript = exporter.export
+    #
+    class Typescript < Base
+      # Type mappings from DSL types to TypeScript 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 TS 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" => "Record<string, unknown>",
+        "map_by_field" => "Record<string, unknown>",
+
+        # Arrays
+        "array" => "unknown[]",
+        "empty_array" => "never[]",
+        "json_array" => "unknown[]",
+        "indices_pair" => "[number, number]"
+      }.freeze
+
+      def export
+        lines = []
+
+        # Add header comment
+        lines << "// Generated from Synthra schema: #{schema.name}"
+        lines << "// Version: #{schema.version}" if schema.version
+        lines << "// DEPRECATED: #{schema.deprecation_message}" if schema.deprecated?
+        lines << ""
+
+        # Export referenced schemas first
+        exported = Set.new
+        collect_referenced_schemas.each do |ref_schema|
+          lines << build_interface(ref_schema)
+          lines << ""
+          exported << ref_schema.name
+        end
+
+        # Export main schema
+        lines << build_interface(schema) unless exported.include?(schema.name)
+
+        lines.join("\n")
+      end
+
+      # Export all schemas in a registry
+      #
+      # @param registry [Registry] the registry
+      # @param options [Hash] export options
+      # @return [String] TypeScript interfaces
+      #
+      def self.export_all(registry, **options)
+        lines = []
+        lines << "// Generated from Synthra schemas"
+        lines << "// Schemas: #{registry.names.join(', ')}"
+        lines << ""
+
+        registry.schemas.each do |name, schema|
+          exporter = new(schema, registry: registry, **options)
+          lines << exporter.build_interface(schema)
+          lines << ""
+        end
+
+        lines.join("\n")
+      end
+
+      def build_interface(target_schema)
+        lines = []
+        
+        if target_schema.deprecated?
+          lines << "/** @deprecated #{target_schema.deprecation_message || 'This interface is deprecated'} */"
+        end
+
+        lines << "interface #{target_schema.name} {"
+
+        target_schema.fields.each do |field|
+          ts_type = field_to_typescript(field)
+          optional = field.optional? ? "?" : ""
+          nullable = field.nullable? ? " | null" : ""
+          
+          # Add JSDoc for complex fields
+          comment = build_field_comment(field)
+          lines << "  #{comment}" if comment
+          
+          lines << "  #{field.name}#{optional}: #{ts_type}#{nullable};"
+        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
+            # Recursively collect nested schemas
+            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_typescript(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"
+          build_map_by_field_type(type_args)
+        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 unknown.
+            "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)
+            "#{element}[]"
+          elsif TYPE_MAPPINGS[element.to_s]
+            "#{TYPE_MAPPINGS[element.to_s]}[]"
+          else
+            # Unknown element types are string-producing types (e.g. array(string)).
+            "string[]"
+          end
+        else
+          "unknown[]"
+        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 : "unknown"
+        end
+        types.join(" | ")
+      end
+
+      def build_map_by_field_type(args)
+        entries = args[:entries] || {}
+        if entries.empty?
+          "Record<string, unknown>"
+        else
+          # Create a more specific type for known entries
+          entry_types = entries.map do |name, info|
+            schema_name = info.is_a?(Hash) ? (info[:schema] || info["schema"]) : info.to_s
+            type = schema_reference?(schema_name) ? schema_name : "unknown"
+            "#{name}: #{type}"
+          end
+          "{ [key: string]: { #{entry_types.join('; ')} }[typeof key] }"
+        end
+      end
+
+      def build_field_comment(field)
+        return nil unless options[:comments]
+
+        comments = []
+        comments << "@type #{field.type_name}" if field.type_name
+        comments << "@optional" if field.optional?
+        comments << "@nullable" if field.nullable?
+
+        return nil if comments.empty?
+        "/** #{comments.join(' ')} */"
+      end
+    end
+    # :nocov:
+  end
+end