synthra 0.1.0

data/lib/synthra/utils/string_distance.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra String Distance Utilities
+# =============================================================================
+#
+# Provides string distance algorithms for "did you mean" suggestions in
+# error messages. The primary algorithm is Levenshtein distance.
+#
+# @example Find similar strings
+#   StringDistance.levenshtein("uuid", "ulid")  # => 2
+#   StringDistance.similar_strings("uui", ["uuid", "ulid", "name"], max_distance: 2)
+#   # => ["uuid", "ulid"]
+#
+# =============================================================================
+
+
+module Synthra
+  module Utils
+
+    # String distance calculations for "did you mean" suggestions
+    #
+    # Provides methods to calculate edit distance between strings and
+    # find similar strings from a collection.
+    #
+    # @example Find similar type names
+    #   StringDistance.similar_strings("strig", Synthra::Types::Registry.names)
+    #   # => ["string", "text"]
+    #
+
+    module StringDistance
+      class << self
+        # Calculate Levenshtein distance between two strings
+        #
+        # The Levenshtein distance is the minimum number of single-character
+        # edits (insertions, deletions, or substitutions) required to
+        # transform one string into another.
+        #
+        # @param str1 [String] first string
+        # @param str2 [String] second string
+        # @return [Integer] the edit distance
+        #
+        # @example
+        #   StringDistance.levenshtein("uuid", "ulid")  # => 2
+        #   StringDistance.levenshtein("text", "text")  # => 0
+        #   StringDistance.levenshtein("", "abc")       # => 3
+        #
+        def levenshtein(str1, str2)
+          str1 = str1.to_s.downcase
+          str2 = str2.to_s.downcase
+
+          return str2.length if str1.empty?
+          return str1.length if str2.empty?
+          return 0 if str1 == str2
+
+          # Create matrix
+          m = str1.length
+          n = str2.length
+          d = Array.new(m + 1) { Array.new(n + 1) }
+
+          # Initialize first column
+          (0..m).each { |i| d[i][0] = i }
+
+          # Initialize first row
+          (0..n).each { |j| d[0][j] = j }
+
+          # Fill in the rest of the matrix
+          (1..m).each do |i|
+            (1..n).each do |j|
+              cost = str1[i - 1] == str2[j - 1] ? 0 : 1
+              d[i][j] = [
+                d[i - 1][j] + 1,      # deletion
+                d[i][j - 1] + 1,      # insertion
+                d[i - 1][j - 1] + cost # substitution
+              ].min
+            end
+          end
+
+          d[m][n]
+        end
+
+        # Find strings similar to a target from a collection
+        #
+        # Returns strings that are within the specified edit distance of
+        # the target, sorted by distance (closest first).
+        #
+        # @param target [String] the string to match
+        # @param candidates [Array<String>] collection to search
+        # @param max_distance [Integer] maximum edit distance (default: 3)
+        # @param limit [Integer] maximum number of results (default: 3)
+        # @return [Array<String>] similar strings, sorted by distance
+        #
+        # @example
+        #   StringDistance.similar_strings("uui", ["uuid", "ulid", "name"])
+        #   # => ["uuid"]
+        #
+        #   StringDistance.similar_strings("tex", ["text", "next", "email"], max_distance: 2)
+        #   # => ["text", "next"]
+        #
+        def similar_strings(target, candidates, max_distance: 3, limit: 3)
+          target = target.to_s
+
+          candidates
+            .map { |c| [c, levenshtein(target, c)] }
+            .select { |_, dist| dist <= max_distance }
+            .sort_by { |_, dist| dist }
+            .first(limit)
+            .map(&:first)
+        end
+
+        # Format "did you mean" suggestion text
+        #
+        # @param suggestions [Array<String>] list of suggestions
+        # @return [String, nil] formatted suggestion text or nil if empty
+        #
+        # @example
+        #   StringDistance.format_suggestions(["uuid", "ulid"])
+        #   # => "Did you mean: uuid, ulid?"
+        #
+        #   StringDistance.format_suggestions([])
+        #   # => nil
+        #
+        def format_suggestions(suggestions)
+          return nil if suggestions.nil? || suggestions.empty?
+
+          "Did you mean: #{suggestions.join(", ")}?"
+        end
+      end
+    end
+  end
+end
+

data/lib/synthra/validator/dsl_validator.rb

@@ -0,0 +1,339 @@
+# frozen_string_literal: true
+
+require "set"
+
+# =============================================================================
+#
+# Synthra Simulyra DSL Validator
+# =============================================================================
+#
+# Validates the Simulyra DSL structure according to the strict separation
+# rules between Schema, API, and Scenario layers.
+#
+# Validation Rules:
+# - No duplicate schema names
+# - All schema(:Name) references resolve to existing schemas
+# - APIs have at least one scenario
+# - Scenarios have @status directive
+# - Probability sum does not exceed 100%
+# - No HTTP directives in schema blocks
+# - No schema field definitions in API blocks
+#
+# @example Validate a ProgramNode
+#   validator = DslValidator.new(program_node)
+#   validator.validate!
+#
+# =============================================================================
+
+module Synthra
+  module Validator
+    # Validates Simulyra DSL AST structure
+    #
+    # The DslValidator checks that the DSL follows the strict separation
+    # between Schema, API, and Scenario layers.
+    #
+    # @example Validate all rules
+    #   validator = DslValidator.new(program_node)
+    #   errors = validator.validate  # Returns array of ValidationError
+    #
+    # @example Raise on first error
+    #   validator = DslValidator.new(program_node)
+    #   validator.validate!  # Raises ValidationError
+    #
+    class DslValidator
+      # HTTP-related directives that are only valid in scenarios
+      HTTP_DIRECTIVES = %w[status probability latency header method].freeze
+
+      # Valid HTTP status codes
+      VALID_STATUS_CODES = (100..599).freeze
+
+      # @param program [Parser::AST::ProgramNode] the AST to validate
+      def initialize(program)
+        @program = program
+        @errors = []
+        @schema_names = Set.new
+      end
+
+      # Validate the DSL and return all errors
+      #
+      # @return [Array<Errors::ValidationError>] list of validation errors
+      #
+      def validate
+        @errors = []
+        @schema_names = Set.new
+
+        # Collect all schema names first (for reference validation)
+        collect_schema_names
+
+        # Run all validation rules
+        validate_no_duplicate_schemas
+        validate_schema_references
+        validate_apis_have_scenarios
+        validate_scenarios_have_status
+        validate_probability_sums
+        validate_schema_context
+        validate_api_context
+
+        @errors
+      end
+
+      # Validate and raise on first error
+      #
+      # @raise [Errors::ValidationError] if any validation fails
+      # @return [true] if all validations pass
+      #
+      def validate!
+        errors = validate
+        raise errors.first if errors.any?
+        true
+      end
+
+      private
+
+      # Collect all schema names for reference validation
+      #
+      # @return [void]
+      #
+      def collect_schema_names
+        @program.schemas.each do |schema|
+          @schema_names.add(schema.name)
+        end
+
+        # Also collect legacy schema names
+        @program.legacy_schemas.each do |schema|
+          @schema_names.add(schema.name)
+        end
+      end
+
+      # Validate no duplicate schema names
+      #
+      # @return [void]
+      #
+      def validate_no_duplicate_schemas
+        seen = {}
+
+        all_schemas = @program.schemas + @program.legacy_schemas
+        all_schemas.each do |schema|
+          if seen.key?(schema.name)
+            @errors << Errors::SchemaError.new(
+              "Duplicate schema \"#{schema.name}\"",
+              line: schema.line,
+              suggestion: "Defined again at line #{schema.line}. Schema names must be unique."
+            )
+          else
+            seen[schema.name] = schema
+          end
+        end
+      end
+
+      # Validate that all schema(:Name) references resolve
+      #
+      # @return [void]
+      #
+      def validate_schema_references
+        # Check schema references in schemas
+        all_schemas = @program.schemas + @program.legacy_schemas
+        all_schemas.each do |schema|
+          schema.fields.each do |field|
+            validate_type_references(field.type_node, schema.name)
+          end
+        end
+
+        # Check schema references in API scenarios
+        @program.apis.each do |api|
+          api.scenarios.each do |scenario|
+            scenario.response_fields.each do |field|
+              validate_type_references(field.type_node, "API #{api.method.upcase} #{api.path}")
+            end
+          end
+        end
+      end
+
+      # Validate type node for schema references
+      #
+      # @param type_node [Parser::AST::TypeNode] the type to validate
+      # @param context [String] context for error message
+      # @return [void]
+      #
+      def validate_type_references(type_node, context)
+        return unless type_node.is_a?(Parser::AST::SchemaReferenceNode)
+
+        unless @schema_names.include?(type_node.schema_name)
+          similar = find_similar_names(type_node.schema_name, @schema_names.to_a)
+          suggestion = similar.any? ? "Did you mean: #{similar.join(', ')}?" : nil
+
+          @errors << Errors::ReferenceError.new(
+            "Schema \"#{type_node.schema_name}\" is not defined",
+            line: type_node.line,
+            suggestion: "#{suggestion} Used in #{context}."
+          )
+        end
+      end
+
+      # Validate that APIs have at least one scenario
+      #
+      # @return [void]
+      #
+      def validate_apis_have_scenarios
+        @program.apis.each do |api|
+          if api.scenarios.empty?
+            @errors << Errors::ApiError.new(
+              "API #{api.method.upcase} #{api.path} must define at least one scenario",
+              line: api.line,
+              suggestion: "Add a scenario block with @status directive."
+            )
+          end
+        end
+      end
+
+      # Validate that scenarios have @status directive
+      #
+      # @return [void]
+      #
+      def validate_scenarios_have_status
+        @program.apis.each do |api|
+          api.scenarios.each do |scenario|
+            unless scenario.status_code
+              @errors << Errors::ScenarioError.new(
+                "Scenario \"#{scenario.name}\" must define @status",
+                line: scenario.line,
+                suggestion: "Required for HTTP simulation. Example: @status 200"
+              )
+            end
+
+            # Also validate status code is valid
+            if scenario.status_code && !VALID_STATUS_CODES.include?(scenario.status_code)
+              @errors << Errors::ScenarioError.new(
+                "Invalid status code #{scenario.status_code} in scenario \"#{scenario.name}\"",
+                line: scenario.line,
+                suggestion: "Status code must be between 100 and 599."
+              )
+            end
+          end
+        end
+      end
+
+      # Validate that probability sums don't exceed 100%
+      #
+      # @return [void]
+      #
+      def validate_probability_sums
+        @program.apis.each do |api|
+          total = 0
+          api.scenarios.each do |scenario|
+            total += scenario.probability if scenario.probability
+          end
+
+          if total > 100
+            @errors << Errors::ScenarioError.new(
+              "Total scenario probability exceeds 100%",
+              line: api.line,
+              suggestion: "Current total: #{total}% in API #{api.method.upcase} #{api.path}."
+            )
+          end
+        end
+      end
+
+      # Validate schema context (no HTTP directives in schemas)
+      #
+      # @return [void]
+      #
+      def validate_schema_context
+        all_schemas = @program.schemas + @program.legacy_schemas
+        all_schemas.each do |schema|
+          schema.behaviors.each do |behavior|
+            if HTTP_DIRECTIVES.include?(behavior.name.to_s)
+              @errors << Errors::ContextError.new(
+                "HTTP directives are not allowed inside schema definitions",
+                line: behavior.line,
+                suggestion: "@#{behavior.name} is an HTTP directive. Use it in scenario blocks only."
+              )
+            end
+          end
+        end
+      end
+
+      # Validate API context (scenarios should be properly nested)
+      #
+      # @return [void]
+      #
+      def validate_api_context
+        @program.apis.each do |api|
+          # Check for duplicate scenario names within an API
+          seen_scenarios = {}
+          api.scenarios.each do |scenario|
+            if seen_scenarios.key?(scenario.name)
+              @errors << Errors::ScenarioError.new(
+                "Duplicate scenario name \"#{scenario.name}\" in API #{api.method.upcase} #{api.path}",
+                line: scenario.line,
+                suggestion: "Scenario names must be unique within an API."
+              )
+            else
+              seen_scenarios[scenario.name] = scenario
+            end
+          end
+
+          # Check for multiple @status directives in a scenario
+          api.scenarios.each do |scenario|
+            status_count = scenario.directives.count { |d| d.is_a?(Parser::AST::StatusDirective) }
+            if status_count > 1
+              @errors << Errors::ScenarioError.new(
+                "Multiple @status directives are not allowed",
+                line: scenario.line,
+                suggestion: "First defined in scenario \"#{scenario.name}\". Use only one @status per scenario."
+              )
+            end
+          end
+        end
+      end
+
+      # Find similar names using basic string distance
+      #
+      # @param target [String] the name to match
+      # @param candidates [Array<String>] possible matches
+      # @return [Array<String>] similar names
+      #
+      def find_similar_names(target, candidates, max_results: 3)
+        scored = candidates.map do |name|
+          [name, levenshtein_distance(target.downcase, name.downcase)]
+        end
+
+        scored.select { |_, dist| dist <= 3 }
+              .sort_by { |_, dist| dist }
+              .first(max_results)
+              .map(&:first)
+      end
+
+      # Simple Levenshtein distance implementation
+      #
+      # @param s1 [String] first string
+      # @param s2 [String] second string
+      # @return [Integer] edit distance
+      #
+      def levenshtein_distance(s1, s2)
+        m = s1.length
+        n = s2.length
+        return n if m.zero?
+        return m if n.zero?
+
+        d = Array.new(m + 1) { Array.new(n + 1, 0) }
+
+        (0..m).each { |i| d[i][0] = i }
+        (0..n).each { |j| d[0][j] = j }
+
+        (1..m).each do |i|
+          (1..n).each do |j|
+            cost = s1[i - 1] == s2[j - 1] ? 0 : 1
+            d[i][j] = [
+              d[i - 1][j] + 1,      # deletion
+              d[i][j - 1] + 1,      # insertion
+              d[i - 1][j - 1] + cost # substitution
+            ].min
+          end
+        end
+
+        d[m][n]
+      end
+    end
+  end
+end