spec_forge 0.7.1 → 1.0.0

data/lib/spec_forge/loader.rb

@@ -2,243 +2,128 @@
 
 module SpecForge
   #
-  # Responsible for loading specs from YAML files and converting them to testable objects
+  # Loads and processes blueprint YAML files into executable Blueprint objects
   #
-  # The Loader reads spec files, parses them as YAML, and transforms them into
-  # a structure that can be used to create Forge objects. It also extracts
-  # metadata like line numbers for error reporting.
-  #
-  # @example Loading all specs
-  #   specs = Loader.load_from_files
+  # The Loader handles the load-time phase of SpecForge, reading YAML files,
+  # parsing steps with line numbers, expanding includes, flattening hierarchies,
+  # and applying filters.
   #
   class Loader
-    class << self
-      #
-      # Loads all spec YAML files and transforms them into normalized structures
-      #
-      # @return [Array<Array>] Array of [global, metadata, specs] for each loaded file
-      #
-      def load_from_files
-        # metadata is not normalized because its not user managed
-        load_specs_from_files.map do |global, metadata, specs|
-          global =
-            begin
-              Normalizer.normalize!(global, using: :global_context)
-            rescue => e
-              raise Error::SpecLoadError.new(e, metadata[:relative_path])
-            end
-
-          specs =
-            specs.map do |spec|
-              Normalizer.normalize!(spec, using: :spec, label: "spec \"#{spec[:name]}\"")
-            rescue => e
-              raise Error::SpecLoadError.new(e, metadata[:relative_path], spec:)
-            end
-
-          [global, metadata, specs]
-        end
-      end
+    #
+    # Loads blueprints from disk with optional filtering
+    #
+    # @param base_path [Pathname, String, nil] Base directory for glob loading (defaults to blueprints/)
+    # @param paths [Array<Pathname, String>] Specific file paths to load (no globbing)
+    # @param tags [Array<String>] Tags to include
+    # @param skip_tags [Array<String>] Tags to exclude
+    #
+    # @return [Array<Blueprint>, Hash] Loaded blueprint objects and any forge hooks
+    #
+    def self.load_blueprints(base_path: nil, paths: [], tags: [], skip_tags: [])
+      new(base_path:, paths:, filter: {tags:, skip_tags:}).load
+    end
 
-      #
-      # Internal method that handles loading specs from files
-      #
-      # This method coordinates the entire spec loading process by:
-      # 1. Reading files from the specs directory
-      # 2. Parsing them as YAML
-      # 3. Transforming them into the proper structure
-      #
-      # @return [Array<Array>] Array of [global, metadata, specs] for each loaded file
-      #
-      # @private
-      #
-      def load_specs_from_files
-        files = read_from_files
-        parse_and_transform_specs(files)
-      end
+    #
+    # Creates a new Loader with the specified base path and filter options
+    #
+    # @param base_path [Pathname, String, nil] Base directory for glob loading (defaults to blueprints/)
+    # @param paths [Array<Pathname, String>] Specific file paths to load (no globbing)
+    # @param filter [Hash] Filter options for tags and skip_tags
+    #
+    # @return [Loader] A new loader instance
+    #
+    def initialize(base_path: nil, paths: [], filter: {})
+      @base_path = base_path.present? ? Pathname.new(base_path) : SpecForge.forge_path.join("blueprints")
+      @paths = Array.wrap(paths).map { |p| Pathname.new(p) }
+      @filter = filter
+    end
 
-      #
-      # Reads spec files from the spec_forge/specs directory
-      #
-      # @return [Array<Array<String, String>>] Array of [file_path, file_content] pairs
-      #
-      # @private
-      #
-      def read_from_files
-        path = SpecForge.forge_path.join("specs")
-
-        Dir[path.join("**/*.yml")].map do |file_path|
-          [file_path, File.read(file_path)]
-        end
-      end
+    #
+    # Loads and processes all blueprints, extracting any hook data at the same time
+    #
+    # @return [Array<Blueprint>, Hash] Loaded blueprint objects and any forge hooks
+    #
+    def load
+      blueprints, forge_hooks = read_blueprints
+        .index_by { |b| b[:name] }
+        .then { |blueprints| StepProcessor.new(blueprints).run }
 
-      #
-      # Parses YAML content and extracts line numbers for error reporting
-      #
-      # @param files [Array<Array<String, String>>] Array of [file_path, file_content] pairs
-      #
-      # @return [Array<Array>] Array of [global, metadata, specs] for each file
-      #
-      # @private
-      #
-      def parse_and_transform_specs(files)
-        base_path = SpecForge.forge_path.join("specs")
-
-        files.map do |file_path, content|
-          relative_path = Pathname.new(file_path).relative_path_from(base_path)
-
-          hash = YAML.safe_load(content, symbolize_names: true)
-
-          file_line_numbers = extract_line_numbers(content, hash)
-
-          # Currently, only holds onto global variables
-          global = hash.delete(:global) || {}
-
-          metadata = {
-            file_name: relative_path.basename(".yml").to_s,
-            relative_path: relative_path.to_s,
-            file_path:
-          }
-
-          specs =
-            hash.map do |spec_name, spec_hash|
-              line_number, *expectation_line_numbers = file_line_numbers[spec_name]
-
-              spec_hash[:id] = "spec_#{SpecForge.generate_id(spec_hash)}"
-              spec_hash[:name] = spec_name.to_s
-              spec_hash[:file_path] = metadata[:file_path]
-              spec_hash[:file_name] = metadata[:file_name]
-              spec_hash[:line_number] = line_number
-
-              # Check for expectations instead of defaulting. I want it to error
-              if (expectations = spec_hash[:expectations])
-                expectations.zip(expectation_line_numbers) do |expectation_hash, line_number|
-                  expectation_hash[:id] = "expect_#{SpecForge.generate_id(expectation_hash)}"
-                  expectation_hash[:name] = build_expectation_name(spec_hash, expectation_hash)
-                  expectation_hash[:line_number] = line_number
-                end
-              end
-
-              spec_hash
-            end
-
-          [global, metadata, specs]
-        end
-      end
+      blueprints = Filter.new(blueprints).run(**@filter).map { |b| Blueprint.new(**b) }
 
-      #
-      # Extracts line numbers from each YAML section for error reporting
-      #
-      # @param content [String] The raw file content
-      # @param input_hash [Hash] The parsed YAML structure
-      #
-      # @return [Hash] A mapping of spec names to line numbers
-      #
-      # @private
-      #
-      def extract_line_numbers(content, input_hash)
-        # I hate this code, lol, and it hates me.
-        # I've tried to make it better, I've tried to clean it up, but every time I break it.
-        # If you know how to make this better, please submit a PR and save me.
-        spec_names = input_hash.keys
-        keys = {}
-
-        current_spec_name = nil
-        expectations_line = nil
-        expectations_indent = nil
-
-        content.lines.each_with_index do |line, index|
-          line_number = index + 1
-          clean_line = line.rstrip
-          indentation = line[/^\s*/].size
-
-          # Skip blank lines
-          next if clean_line.empty?
-
-          # Reset on top-level elements
-          if indentation == 0
-            current_spec_name = nil
-            expectations_line = nil
-            expectations_indent = nil
-
-            # Check if this line starts a spec we're interested in
-            spec_names.each do |spec_name|
-              next unless clean_line.start_with?("#{spec_name}:")
-
-              current_spec_name = spec_name
-              keys[current_spec_name] = [line_number]
-              break
-            end
-
-            next
-          end
+      [blueprints, forge_hooks]
+    end
 
-          # Skip if we're not in a relevant spec
-          next unless current_spec_name
+    private
 
-          # Found expectations section
-          if clean_line.match?(/^[^#]\s*expectations:/i)
-            expectations_line = line_number
-            expectations_indent = indentation
-            next
-          end
+    def read_blueprints
+      # Use specific paths if provided, otherwise glob from base_path
+      file_paths =
+        if @paths.present?
+          @paths
+        else
+          Dir.glob(@base_path.join("**", "*.{yml,yaml}")).map { |p| Pathname.new(p) }
+        end
 
-          # Found an expectation item
-          if expectations_line && clean_line.start_with?("#{" " * expectations_indent}- ")
-            keys[current_spec_name] << line_number
+      file_paths.map do |file_path|
+        content = File.read(file_path)
+
+        # Determine the relative path for naming
+        relative_path =
+          if @paths.present?
+            # For specific paths, use the filename as the base
+            file_path.basename
+          else
+            # For glob loading, use path relative to base_path
+            file_path.relative_path_from(@base_path)
           end
-        end
 
-        keys
+        name = relative_path.to_s.delete_suffix(".yml").delete_suffix(".yaml")
+        steps = parse_steps(content)
+
+        {file_path: relative_path, name:, steps:}
       end
+    end
+
+    def parse_steps(content)
+      # Parse with Psych to make it easier to extract line numbers
+      yaml = Psych.parse(content)
 
-      #
-      # Builds a name for an expectation based on HTTP verb, URL, and optional name
-      #
-      # @param spec_hash [Hash] The spec configuration
-      # @param expectation_hash [Hash] The expectation configuration
-      #
-      # @return [String] A formatted expectation name (e.g., "GET /users - Find User")
-      #
-      # @private
-      #
-      def build_expectation_name(spec_hash, expectation_hash)
-        # Create a structure for http_verb and url
-        # Removing the defaults and validators to avoid triggering extra logic
-        structure = Normalizer.structures[:spec][:structure].slice(:http_verb, :url)
-          .transform_values { |v| v.except(:default, :validator) }
-
-        # Ignore any errors. These will be validated later
-        normalized_spec, _ = Normalizer.normalize(spec_hash, using: structure, label: "n/a")
-        normalized_expectation, _ = Normalizer.normalize(
-          expectation_hash,
-          using: structure, label: "n/a"
-        )
-
-        request_data = normalized_spec.deep_merge(normalized_expectation)
-
-        url = request_data[:url]
-        http_verb = request_data[:http_verb].presence || "GET"
-
-        # Finally generate the name
-        generate_expectation_name(http_verb:, url:, name: expectation_hash[:name])
+      steps = yaml.to_ruby(symbolize_names: true)
+      inject_line_numbers(yaml.root, steps)
+    end
+
+    def inject_line_numbers(yaml_node, ruby_object)
+      case ruby_object
+      when Array
+        inject_line_numbers_into_array(yaml_node, ruby_object)
+      when Hash
+        inject_line_numbers_into_hash(yaml_node, ruby_object)
+      else
+        ruby_object
       end
+    end
 
-      #
-      # Generates an expectation name from its components
-      #
-      # @param http_verb [String] The HTTP verb (GET, POST, etc.)
-      # @param url [String] The URL path
-      # @param name [String, nil] Optional descriptive name
-      #
-      # @return [String] A formatted expectation name
-      #
-      # @private
-      #
-      def generate_expectation_name(http_verb:, url:, name: nil)
-        base = "#{http_verb.upcase} #{url}"   # GET /users
-        base += " - #{name}" if name.present? # GET /users - Returns 404 because y not?
-        base
+    def inject_line_numbers_into_array(yaml_node, array)
+      yaml_node.children
+        .map
+        .with_index { |node, index| inject_line_numbers(node, array[index]) }
+    end
+
+    def inject_line_numbers_into_hash(yaml_node, hash)
+      # Psych uses 0-indexed line numbers
+      hash[:line_number] = yaml_node.start_line + 1
+
+      # Walk through key-value pairs in the YAML tree
+      yaml_node.children.each_slice(2) do |key_node, value_node|
+        key = key_node.value.to_sym
+
+        # Only recursively add line numbers to substeps.
+        next unless key == :steps
+
+        hash[key] = inject_line_numbers(value_node, hash[key])
       end
+
+      hash
     end
   end
 end

data/lib/spec_forge/normalizer/default.rb

@@ -15,7 +15,7 @@ module SpecForge
         structure.each_with_object({}) do |(attribute_name, attribute), hash|
           type = attribute[:type]
           has_default = attribute.key?(:default)
-          required = attribute[:required] != false
+          required = attribute[:required] == true
 
           next if !(include_optional || required || has_default)
 

data/lib/spec_forge/normalizer/structure.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Normalizer
+    #
+    # Represents a parsed structure definition for normalization
+    #
+    # Structure definitions specify the expected shape of input data,
+    # including types, defaults, aliases, and nested structures.
+    # They are loaded from YAML files and normalized themselves.
+    #
+    class Structure < Hash
+      # Meta-structure defining the format of structure definitions
+      #
+      # @return [Hash]
+      STRUCTURE = {
+        type: {
+          type: [String, Array, Class],
+          default: nil, # Important to default this to nil so other logic can handle it
+          required: true,
+          validator: :present?
+        },
+        default: {
+          type: [String, NilClass, Numeric, Array, Hash, TrueClass, FalseClass]
+        },
+        required: {
+          type: [TrueClass, FalseClass]
+        },
+        aliases: {
+          type: Array,
+          structure: {type: String}
+        },
+        structure: {
+          type: Hash
+        },
+        validator: {
+          type: String
+        },
+        transformer: {
+          type: String
+        },
+        description: {
+          type: String
+        },
+        examples: {
+          type: Array,
+          structure: {
+            type: [String, Integer, Float, Hash, Array, TrueClass, FalseClass]
+          }
+        }
+      }.freeze
+
+      # @return [String] Human-readable label for this structure
+      attr_reader :label
+
+      #
+      # Creates a new Structure from the given input definition
+      #
+      # @param input [Hash] The raw structure definition from YAML
+      # @param label [String] Human-readable label for error messages
+      #
+      # @return [Structure] A new structure instance
+      #
+      def initialize(input, label: "")
+        @label = label
+
+        # Pull in the data
+        deep_merge!(input)
+
+        # And normalize
+        normalize
+      end
+
+      private
+
+      def normalize
+        # Normalize the root level keys
+        transform_values!(with_key: true) do |attribute, name|
+          normalize_attribute(name, attribute)
+        end
+
+        self
+      end
+
+      def normalize_attribute(attribute_name, attribute)
+        case attribute
+        # Shorthands for single/multiple types
+        when String, Array
+          hash = {type: resolve_type(attribute)}
+
+          default = Normalizer.default(structure: STRUCTURE)
+          hash.merge!(default)
+        # Full syntax
+        when Hash
+          hash = Normalizer.raise_errors! do
+            Normalizer.new(
+              "#{attribute_name.in_quotes} in #{@label.in_quotes}",
+              attribute,
+              structure: STRUCTURE
+            ).normalize
+          end
+
+          hash[:type] = resolve_type(attribute[:type])
+
+          if hash[:structure].present?
+            hash[:structure] = normalize_structure(attribute_name, hash) || {}
+          end
+
+          hash
+        else
+          raise ArgumentError, "Attribute #{attribute_name.in_quotes}: Expected String, Array, or Hash. Got #{attribute.inspect}"
+        end
+      end
+
+      def normalize_structure(name, hash)
+        if hash[:type] == Array
+          normalize_attribute(name, hash[:structure])
+        elsif hash[:type] == Hash
+          hash[:structure].transform_values(with_key: true) { |v, k| normalize_attribute(k, v) }
+        end
+      end
+
+      def resolve_type(type)
+        if type == "boolean"
+          [FalseClass, TrueClass]
+        elsif type == "any"
+          [Array, FalseClass, Hash, NilClass, Numeric, String, TrueClass]
+        elsif type.instance_of?(Array)
+          type.map { |t| resolve_type(t) }
+        elsif type.is_a?(String)
+          type.classify.constantize
+        else
+          type
+        end
+      rescue NameError => e
+        raise Error, "#{e}. #{type.inspect} is not a valid type found in #{@label.in_quotes}"
+      end
+    end
+  end
+end

data/lib/spec_forge/normalizer/transformers.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Normalizer
+    #
+    # Provides transformation functions for normalizer structure definitions
+    #
+    # Transformers modify values during normalization, such as converting
+    # shorthand syntax into full structures or normalizing type definitions.
+    #
+    class Transformers
+      include Singleton
+
+      #
+      # Calls a transformer method with the given value
+      #
+      # @param method_name [Symbol, String] The transformer method to call
+      # @param value [Object] The value to transform
+      #
+      # @return [Object] The transformed value
+      #
+      def self.call(method_name, value)
+        instance.public_send(method_name, value)
+      end
+
+      #
+      # Normalizes include values to an array of blueprint names
+      #
+      # @param value [String, Array<String>] Include value(s)
+      #
+      # @return [Array<String>] Normalized blueprint names without extensions
+      #
+      def normalize_includes(value)
+        Array(value).map! { |name| name.delete_suffix(".yml").delete_suffix(".yaml") }
+      end
+
+      #
+      # Normalizes callback shorthand into full hash format
+      #
+      # Converts string callback names into the full hash structure with
+      # a :name key. Hashes pass through unchanged. Arrays are processed
+      # recursively to normalize each element.
+      #
+      # @param value [String, Hash, Array] Callback name, full definition, or array of callbacks
+      #
+      # @return [Array<Hash>] Normalized callback hash(es) with :name key
+      #
+      def normalize_callback(value)
+        return if value.blank?
+
+        case value
+        when Hash
+          [value]
+        when Array
+          value.map { |v| normalize_callback(v) }.flatten
+        else
+          [{name: value}]
+        end
+      end
+
+      #
+      # Normalizes a shape definition into a structured schema format
+      #
+      # Converts shorthand shape syntax (arrays, hashes, type strings) into
+      # the full schema structure with :type, :pattern, and :structure keys.
+      #
+      # @param value [Array, Hash, String] The shape definition to normalize
+      #
+      # @return [Hash] Normalized schema structure
+      #
+      # @raise [ArgumentError] If value is nil
+      #
+      def normalize_shape(value)
+        raise ArgumentError, "Shape cannot be nil" if value.nil?
+
+        case value
+        when Array
+          shape = {type: [Array]}
+
+          if value.size == 1
+            shape[:pattern] = normalize_shape(value.first)
+          elsif value.size > 1
+            shape[:structure] = value.map { |i| normalize_shape(i) }
+          else
+            []
+          end
+
+          shape
+        when Hash
+          {
+            type: [Hash],
+            structure: value.transform_values { |v| normalize_shape(v) }
+          }
+        when String
+          result = Type.from_string(value)
+          {type: result[:types], optional: result[:optional]}
+        end
+      end
+
+      #
+      # Normalizes a schema definition by converting type strings to classes
+      #
+      # Recursively processes schema definitions, converting string type
+      # specifications into their Ruby class equivalents.
+      #
+      # @param value [Array, Hash, String] The schema definition to normalize
+      #
+      # @return [Hash, Array] Normalized schema with type classes
+      #
+      # @raise [ArgumentError] If value is nil
+      #
+      def normalize_schema(value)
+        raise ArgumentError, "Schema cannot be nil" if value.nil?
+
+        case value
+        when Array
+          value.each { |v| normalize_schema(v) }
+        when Hash
+          if (type = value[:type]) && type.is_a?(String)
+            result = Type.from_string(type)
+
+            value[:type] = result[:types]
+            value[:optional] = result[:optional] unless value.key?(:optional)
+          end
+
+          # Handle explicit nullable: true (sugar for adding NilClass to type)
+          if value.delete(:nullable)
+            value[:type] ||= []
+            value[:type] << NilClass unless value[:type].include?(NilClass)
+          end
+
+          # Default optional to false if not set
+          value[:optional] ||= false
+
+          if (structure = value[:structure])
+            value[:structure] =
+              case structure
+              when Array
+                structure.map { |v| normalize_schema(v) }
+              when Hash
+                structure.transform_values { |v| normalize_schema(v) }
+              end
+          end
+
+          if (pattern = value[:pattern])
+            value[:pattern] = normalize_schema(pattern)
+          end
+
+          value
+        when String
+          result = Type.from_string(value)
+          {type: result[:types], optional: result[:optional]}
+        end
+      end
+
+      #
+      # Returns the absolute value of a number
+      #
+      # @param value [Numeric, nil] The value to convert
+      #
+      # @return [Numeric, nil] The absolute value, or nil if input is nil
+      #
+      def abs(value)
+        value&.abs
+      end
+    end
+  end
+end