ask-schema 0.1.0

data/lib/ask/schema/dsl/primitive_types.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Ask
+  class Schema
+    module DSL
+      # DSL methods for declaring primitive-type properties.
+      module PrimitiveTypes
+        # Declare a string property.
+        # @param name [Symbol] Property name
+        # @param description [String, nil] Property description
+        # @param required [Boolean] Whether the property is required (default: true)
+        # @param requires [Symbol, Array<Symbol>, nil] Dependent property requirements
+        # @param options [Hash] Additional JSON Schema constraints (enum:, min_length:, pattern:, etc.)
+        def string(name, description: nil, required: true, requires: nil, **options)
+          add_property(name, string_schema(description: description, **options), required: required, requires: requires)
+        end
+
+        # Declare a number property.
+        # @param name [Symbol] Property name
+        # @param description [String, nil] Property description
+        # @param required [Boolean] Whether the property is required (default: true)
+        # @param requires [Symbol, Array<Symbol>, nil] Dependent property requirements
+        # @param options [Hash] Additional JSON Schema constraints (minimum:, maximum:, etc.)
+        def number(name, description: nil, required: true, requires: nil, **options)
+          add_property(name, number_schema(description: description, **options), required: required, requires: requires)
+        end
+
+        # Declare an integer property.
+        # @param name [Symbol] Property name
+        # @param description [String, nil] Property description
+        # @param required [Boolean] Whether the property is required (default: true)
+        # @param requires [Symbol, Array<Symbol>, nil] Dependent property requirements
+        # @param options [Hash] Additional JSON Schema constraints (minimum:, maximum:, etc.)
+        def integer(name, description: nil, required: true, requires: nil, **options)
+          add_property(name, integer_schema(description: description, **options), required: required, requires: requires)
+        end
+
+        # Declare a boolean property.
+        # @param name [Symbol] Property name
+        # @param description [String, nil] Property description
+        # @param required [Boolean] Whether the property is required (default: true)
+        # @param requires [Symbol, Array<Symbol>, nil] Dependent property requirements
+        # @param options [Hash] Additional JSON Schema constraints
+        def boolean(name, description: nil, required: true, requires: nil, **options)
+          add_property(name, boolean_schema(description: description, **options), required: required, requires: requires)
+        end
+
+        # Declare a null property.
+        # @param name [Symbol] Property name
+        # @param description [String, nil] Property description
+        # @param required [Boolean] Whether the property is required (default: true)
+        # @param requires [Symbol, Array<Symbol>, nil] Dependent property requirements
+        # @param options [Hash] Additional JSON Schema constraints
+        def null(name, description: nil, required: true, requires: nil, **options)
+          add_property(name, null_schema(description: description, **options), required: required, requires: requires)
+        end
+      end
+    end
+  end
+end

data/lib/ask/schema/dsl/schema_builders.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+module Ask
+  class Schema
+    module DSL
+      # Core schema builders that generate JSON Schema fragments for each type.
+      #
+      # Each method returns a Hash representing a JSON Schema fragment for
+      # the given type, with all specified constraints.
+      module SchemaBuilders
+        # Build a string schema fragment.
+        # @param description [String, nil] Property description
+        # @param enum [Array<String>, nil] Allowed values
+        # @param min_length [Integer, nil] Minimum string length
+        # @param max_length [Integer, nil] Maximum string length
+        # @param pattern [String, nil] Regex pattern for validation
+        # @param format [String, nil] String format (e.g., "email", "uri")
+        # @return [Hash] JSON Schema fragment
+        def string_schema(description: nil, enum: nil, min_length: nil, max_length: nil, pattern: nil, format: nil)
+          {
+            type: "string",
+            enum: enum,
+            description: description,
+            minLength: min_length,
+            maxLength: max_length,
+            pattern: pattern,
+            format: format
+          }.compact
+        end
+
+        # Build a number schema fragment.
+        # @param description [String, nil] Property description
+        # @param minimum [Numeric, nil] Minimum value
+        # @param maximum [Numeric, nil] Maximum value
+        # @param multiple_of [Numeric, nil] Value must be multiple of this
+        # @param enum [Array<Numeric>, nil] Allowed values
+        # @return [Hash] JSON Schema fragment
+        def number_schema(description: nil, minimum: nil, maximum: nil, multiple_of: nil, enum: nil)
+          {
+            type: "number",
+            description: description,
+            minimum: minimum,
+            maximum: maximum,
+            multipleOf: multiple_of,
+            enum: enum
+          }.compact
+        end
+
+        # Build an integer schema fragment.
+        # @param description [String, nil] Property description
+        # @param minimum [Integer, nil] Minimum value
+        # @param maximum [Integer, nil] Maximum value
+        # @param multiple_of [Integer, nil] Value must be multiple of this
+        # @param enum [Array<Integer>, nil] Allowed values
+        # @return [Hash] JSON Schema fragment
+        def integer_schema(description: nil, minimum: nil, maximum: nil, multiple_of: nil, enum: nil)
+          {
+            type: "integer",
+            description: description,
+            minimum: minimum,
+            maximum: maximum,
+            multipleOf: multiple_of,
+            enum: enum
+          }.compact
+        end
+
+        # Build a boolean schema fragment.
+        # @param description [String, nil] Property description
+        # @return [Hash] JSON Schema fragment
+        def boolean_schema(description: nil)
+          {type: "boolean", description: description}.compact
+        end
+
+        # Build a null schema fragment.
+        # @param description [String, nil] Property description
+        # @return [Hash] JSON Schema fragment
+        def null_schema(description: nil)
+          {type: "null", description: description}.compact
+        end
+
+        # Build an object schema fragment, either inline or via reference.
+        #
+        # When called with a block, defines properties inline.
+        # When called with +:of+, creates a reference to a named definition.
+        # When called with +reference:+ (deprecated), creates a reference.
+        #
+        # @param description [String, nil] Property description
+        # @param of [Symbol, Class, nil] Reference target (definition name or Schema class)
+        # @param reference [Symbol, nil] Deprecated: use +of+ instead
+        # @param block [Proc] Inline property definitions
+        # @return [Hash] JSON Schema fragment
+        def object_schema(description: nil, of: nil, reference: nil, &block)
+          if reference
+            warn "[DEPRECATION] The `reference` option will be deprecated. Please use `of` instead."
+            of = reference
+          end
+
+          if of
+            determine_object_reference(of, description)
+          else
+            sub_schema = Class.new(Schema)
+            result = sub_schema.class_eval(&block)
+
+            if result.is_a?(Hash) && result["$ref"] && sub_schema.properties.empty?
+              result.merge(description ? {description: description} : {})
+            elsif schema_class?(result) && sub_schema.properties.empty?
+              schema_class_to_inline_schema(result).merge(description ? {description: description} : {})
+            else
+              schema = {
+                type: "object",
+                properties: sub_schema.properties,
+                required: sub_schema.required_properties,
+                additionalProperties: sub_schema.additional_properties,
+                description: description
+              }.compact
+
+              merge_conditions(schema, sub_schema)
+            end
+          end
+        end
+
+        # Build an array schema fragment.
+        #
+        # Items can be specified inline via a block, or via the +:of+ option
+        # for simple types, references, or Schema classes.
+        #
+        # @param description [String, nil] Property description
+        # @param of [Symbol, Class, nil] Items type (:string, :number, a definition name, or Schema class)
+        # @param min_items [Integer, nil] Minimum number of items
+        # @param max_items [Integer, nil] Maximum number of items
+        # @param block [Proc] Block for complex item schemas
+        # @return [Hash] JSON Schema fragment
+        def array_schema(description: nil, of: nil, min_items: nil, max_items: nil, &block)
+          items = determine_array_items(of, &block)
+
+          {
+            type: "array",
+            description: description,
+            items: items,
+            minItems: min_items,
+            maxItems: max_items
+          }.compact
+        end
+
+        # Build an +anyOf+ schema fragment.
+        #
+        # @param description [String, nil] Property description
+        # @param block [Proc] Block listing alternative schemas
+        # @return [Hash] JSON Schema fragment
+        def any_of_schema(description: nil, &block)
+          schemas = collect_schemas_from_block(&block)
+
+          {
+            description: description,
+            anyOf: schemas
+          }.compact
+        end
+
+        # Build a +oneOf+ schema fragment.
+        #
+        # @param description [String, nil] Property description
+        # @param block [Proc] Block listing alternative schemas
+        # @return [Hash] JSON Schema fragment
+        def one_of_schema(description: nil, &block)
+          schemas = collect_schemas_from_block(&block)
+
+          {
+            description: description,
+            oneOf: schemas
+          }.compact
+        end
+
+        private
+
+        # Determine the items schema for an array.
+        def determine_array_items(of, &)
+          return collect_schemas_from_block(&).first if block_given?
+          return send("#{of}_schema") if primitive_type?(of)
+          return reference(of) if of.is_a?(Symbol)
+          return schema_class_to_inline_schema(of) if schema_class?(of)
+
+          raise InvalidArrayTypeError, "Invalid array type: #{of.inspect}. Must be a primitive type (:string, :number, etc.), a symbol reference, a Schema class, or a Schema instance."
+        end
+
+        # Determine the target of an object reference.
+        def determine_object_reference(of, description = nil)
+          result = case of
+                   when Symbol
+                     reference(of)
+                   when Class
+                     raise InvalidObjectTypeError, "Invalid object type: #{of.inspect}. Class must inherit from Ask::Schema." unless schema_class?(of)
+
+                     schema_class_to_inline_schema(of)
+                   else
+                     raise InvalidObjectTypeError, "Invalid object type: #{of.inspect}. Must be a symbol reference, a Schema class, or a Schema instance." unless schema_class?(of)
+
+                     schema_class_to_inline_schema(of)
+                   end
+
+          description ? result.merge(description: description) : result
+        end
+
+        # Collect schemas from a composition block (any_of, one_of).
+        def collect_schemas_from_block(&block)
+          schemas = []
+          schema_builder = self
+
+          context = Object.new
+
+          schema_builder.methods.grep(/_schema$/).each do |schema_method|
+            type_name = schema_method.to_s.sub(/_schema$/, "")
+
+            context.define_singleton_method(type_name) do |_name = nil, **options, &blk|
+              schemas << schema_builder.send(schema_method, **options, &blk)
+            end
+          end
+
+          context.define_singleton_method(:const_missing) do |name|
+            const_get(name) if const_defined?(name)
+          end
+
+          context.instance_eval(&block)
+          schemas
+        end
+
+        # Convert a Schema class (or instance) into an inline object schema hash.
+        def schema_class_to_inline_schema(schema_class_or_instance)
+          schema_class = if schema_class_or_instance.is_a?(Class)
+                           schema_class_or_instance
+                         else
+                           schema_class_or_instance.class
+                         end
+
+          {
+            type: "object",
+            properties: schema_class.properties,
+            required: schema_class.required_properties,
+            additionalProperties: schema_class.additional_properties
+          }.tap do |schema|
+            description = if schema_class_or_instance.is_a?(Class)
+                            schema_class.description
+                          else
+                            schema_class_or_instance.instance_variable_get(:@description) || schema_class.description
+                          end
+
+            schema[:description] = description if description
+
+            merge_conditions(schema, schema_class)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/schema/dsl/utilities.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Ask
+  class Schema
+    module DSL
+      # Utility methods for schema definitions, references, and property registration.
+      module Utilities
+        # Define a named sub-schema for reuse via {reference}.
+        #
+        # Named definitions appear in the output under `$defs`.
+        #
+        # @example
+        #   define(:address) do
+        #     string :street
+        #     string :city
+        #   end
+        #
+        # @param name [Symbol] The definition name (used in $ref)
+        # @param block [Proc] DSL block for the sub-schema properties
+        def define(name, &)
+          sub_schema = Class.new(Schema)
+          sub_schema.class_eval(&)
+
+          schema = {
+            type: "object",
+            properties: sub_schema.properties,
+            required: sub_schema.required_properties,
+            additionalProperties: sub_schema.additional_properties
+          }
+
+          merge_conditions(schema, sub_schema)
+
+          definitions[name] = schema
+        end
+
+        # Create a `$ref` reference to a named definition or root.
+        #
+        # Use with +object+ or +array+ via the +:of+ option, or standalone
+        # to produce a reference hash.
+        #
+        # @example
+        #   reference(:address)  # => { "$ref" => "#/$defs/address" }
+        #   reference(:root)     # => { "$ref" => "#" }
+        #
+        # @param schema_name [Symbol] The definition name, or +:root+ for root reference
+        # @return [Hash{"$ref" => String}] The reference
+        def reference(schema_name)
+          if schema_name == :root
+            {"$ref" => "#"}
+          else
+            {"$ref" => "#/$defs/#{schema_name}"}
+          end
+        end
+
+        private
+
+        # Register a property on the schema class.
+        #
+        # @param name [Symbol] Property name
+        # @param definition [Hash] JSON Schema fragment for the property
+        # @param required [Boolean] Whether the property is required
+        # @param requires [Symbol, Array<Symbol>, nil] Dependent property requirements
+        # @return [nil]
+        def add_property(name, definition, required:, requires: nil)
+          property_name = name.to_sym
+
+          properties[property_name] = definition
+          if required
+            required_properties << property_name unless required_properties.include?(property_name)
+          else
+            required_properties.delete(property_name)
+          end
+
+          if requires
+            builder = ConditionalBuilder.new
+            builder.requires(*Array(requires))
+            dependencies[name.to_s] = builder
+          end
+
+          nil
+        end
+
+        # Check if a type is a primitive JSON Schema type.
+        # @param type [Symbol] The type to check
+        # @return [Boolean]
+        def primitive_type?(type)
+          type.is_a?(Symbol) && PRIMITIVE_TYPES.include?(type)
+        end
+
+        # Check if a value is a Schema class or instance.
+        # @param type [Object] The value to check
+        # @return [Boolean]
+        def schema_class?(type)
+          (type.is_a?(Class) && type < Schema) || type.is_a?(Schema)
+        end
+      end
+    end
+  end
+end

data/lib/ask/schema/dsl.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "dsl/schema_builders"
+require_relative "dsl/primitive_types"
+require_relative "dsl/complex_types"
+require_relative "dsl/conditionals"
+require_relative "dsl/utilities"
+
+module Ask
+  class Schema
+    # Assembles all DSL modules into the Schema class.
+    #
+    # Includes {SchemaBuilders}, {PrimitiveTypes}, {ComplexTypes},
+    # {Conditionals}, and {Utilities} to provide the full schema
+    # definition DSL.
+    module DSL
+      include SchemaBuilders
+      include PrimitiveTypes
+      include ComplexTypes
+      include Conditionals
+      include Utilities
+    end
+  end
+end

data/lib/ask/schema/errors.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Ask
+  class Schema
+    # Base error class for all schema-related errors.
+    class Error < StandardError; end
+
+    # Raised when an invalid schema type is specified.
+    class InvalidSchemaTypeError < Error
+      # @param type [Symbol] The unrecognized type
+      def initialize(type)
+        super("Unknown schema type: #{type}")
+      end
+    end
+
+    # Raised when an invalid type is passed to +array+ via the +:of+ option.
+    class InvalidArrayTypeError < Error; end
+
+    # Raised when an invalid type is passed to +object+ via the +:of+ option.
+    class InvalidObjectTypeError < Error; end
+
+    # Raised when a schema definition is structurally invalid.
+    class InvalidSchemaError < Error; end
+
+    # Raised when schema validation fails (e.g., circular references).
+    class ValidationError < Error; end
+
+    # Raised when a maximum or limit is exceeded.
+    class LimitExceededError < Error; end
+  end
+end

data/lib/ask/schema/helpers.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Ask
+  class Schema
+    # Convenience helpers for creating schemas in a top-level context.
+    module Helpers
+      # Create a new schema instance using a DSL block.
+      #
+      # @param name [String, nil] Schema name
+      # @param description [String, nil] Schema description
+      # @param block [Proc] DSL block with type definitions
+      # @return [Schema] A new schema instance
+      def schema(name = nil, description: nil, &block)
+        schema_class = Ask::Schema.create(&block)
+        schema_class.new(name, description: description)
+      end
+    end
+  end
+end

data/lib/ask/schema/json_output.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  class Schema
+    # Generates JSON Schema output from a Schema class definition.
+    module JsonOutput
+      # Generate a hash representation of the JSON Schema.
+      #
+      # Validates the schema before generating output. The returned hash
+      # includes +:name+, +:description+, and +:schema+ keys.
+      #
+      # @return [Hash] The JSON Schema representation
+      # @raise [ValidationError] if the schema is invalid
+      def to_json_schema
+        validate!
+
+        schema_hash = {
+          type: "object",
+          properties: self.class.properties,
+          required: self.class.required_properties,
+          additionalProperties: self.class.additional_properties
+        }
+
+        schema_hash[:strict] = self.class.strict unless self.class.strict.nil?
+
+        schema_hash["$defs"] = self.class.definitions unless self.class.definitions.empty?
+
+        self.class.send(:merge_conditions, schema_hash, self.class)
+
+        {
+          name: @name,
+          description: @description || self.class.description,
+          schema: schema_hash
+        }
+      end
+
+      # Generate a pretty-printed JSON string of the schema.
+      #
+      # @return [String] Pretty-printed JSON
+      # @raise [ValidationError] if the schema is invalid
+      def to_json(*_args)
+        validate!
+        JSON.pretty_generate(to_json_schema)
+      end
+    end
+  end
+end

data/lib/ask/schema/validator.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Ask
+  class Schema
+    # Validates schema definitions for structural issues such as circular
+    # references in named definitions (`$defs`).
+    #
+    # Uses DFS-based topological sort with three-color marking (WHITE/GRAY/BLACK)
+    # to detect cycles in definition dependency graphs.
+    class Validator
+      # Node states for DFS-based topological sort
+      WHITE = :white  # No mark (unvisited)
+      GRAY = :gray    # Temporary mark (currently being processed)
+      BLACK = :black  # Permanent mark (completely processed)
+
+      # @param schema_class [Class<Schema>] The schema class to validate
+      def initialize(schema_class)
+        @schema_class = schema_class
+      end
+
+      # Run all validations, raising on the first error.
+      #
+      # @return [nil] if the schema is valid
+      # @raise [ValidationError] if a circular reference is detected
+      def validate!
+        validate_circular_references!
+      end
+
+      # Check if the schema is valid without raising.
+      #
+      # @return [Boolean]
+      def valid?
+        validate!
+        true
+      rescue ValidationError
+        false
+      end
+
+      private
+
+      # Detect circular references in $defs using DFS.
+      def validate_circular_references!
+        definitions = @schema_class.definitions
+        return if definitions.empty?
+
+        marks = Hash.new { WHITE }
+
+        definitions.each_key do |node|
+          visit(node, definitions, marks) if marks[node] == WHITE
+        end
+      end
+
+      # DFS visit function with three-color marking.
+      def visit(node, definitions, marks)
+        return if marks[node] == BLACK
+
+        raise ValidationError, "Circular reference detected involving '#{node}'" if marks[node] == GRAY
+
+        marks[node] = GRAY
+
+        definition = definitions[node]
+        if definition && definition[:properties]
+          definition[:properties].each_value do |property|
+            extract_references(property).each do |adjacent_node|
+              visit(adjacent_node, definitions, marks)
+            end
+          end
+        end
+
+        marks[node] = BLACK
+      end
+
+      # Recursively extract `$ref` references from a property definition.
+      #
+      # @param property [Hash, Array] A property definition or nested structure
+      # @return [Array<Symbol>] Referenced definition names
+      def extract_references(property)
+        references = []
+
+        case property
+        when Hash
+          if property["$ref"]
+            ref_name = property["$ref"].split("/").last&.to_sym
+            references << ref_name if ref_name
+          else
+            property.each_value do |value|
+              references.concat(extract_references(value))
+            end
+          end
+        when Array
+          property.each do |item|
+            references.concat(extract_references(item))
+          end
+        end
+
+        references
+      end
+    end
+  end
+end

data/lib/ask/schema/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ask
+  class Schema
+    VERSION = "0.1.0"
+  end
+end