satisfactory 0.0.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d75154f80250b3760e281317aeb9dbe5943df83925488c3e66164ace3736f422
-  data.tar.gz: a29f35668835598adc52196519d9ca849354c9c0ed23a62d1bbb3997a2343db6
+  metadata.gz: 06dfe6edd70f452888cfeb3d5379a592a3d88983c5651024cdc634dad1af3ca5
+  data.tar.gz: f50122a32a4068fd77e3fb6d4639957117ceaf7592af1530bf35e0b4a2b9594f
 SHA512:
-  metadata.gz: 3dfcf2f1eaf54ffe8345fac3efd11351c26e0b3840457727bf378cbbfadb47d93a01f39fb26cc6e2753ee92016a4b048d55f9d1e99d3c54d93778cb6b8b68e78
-  data.tar.gz: 514ed076dbc00f6313be39609a1b7cb48dbf309247870e6bda9a6af7ff3a6c21d59dbd126c0ee33197e4f07226a9b9c6a80972fb8d92c2fa40cf47a96c31d48c
+  metadata.gz: 6fe4c14011c38c9b3116e20b501ce8d65dcc458cd63b9fe44dd1e8291db5ca535d61d63069bc95b118342d17550e5c424aea7217bb5802a51df0cc74e8a0cbf8
+  data.tar.gz: 522edd69c8e2e31138e7a8cd0fe5521135b5bf42b544c2f9511ef8aa5144635a8cc3a3b953c9578446d041a6144b1e367723c6d7d00f3c679c2bdb0ce0955d17

data/LICENCE

@@ -0,0 +1,2 @@
+ Satisfactory © 2022 by Smart/Casual Ltd is licensed under CC BY-NC-SA 4.0.
+ To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/4.0/

data/Rakefile

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require "bundler/gem_tasks"
 require "rubocop/rake_task"
 

data/lib/satisfactory/collection.rb

@@ -0,0 +1,61 @@
+require_relative "upstream_record_finder"
+
+module Satisfactory
+  # Represents a collection of homogenous records.
+  class Collection < Array
+    # @api private
+    def initialize(*args, upstream:, **kwargs, &block)
+      super(*args, **kwargs, &block)
+      @upstream = upstream
+    end
+
+    # @api private
+    attr_reader :upstream
+
+    # @!method and
+    #   Delegates to the upstream record.
+    #   @return (see Satisfactory::Record#and)
+    #   @see Satisfactory::Record#and
+    # @!method create
+    #   Delegates to the upstream record.
+    #   @return (see Satisfactory::Record#create)
+    #   @see Satisfactory::Record#create
+    # @!method to_plan
+    #   Delegates to the upstream record.
+    #   @return (see Satisfactory::Record#to_plan)
+    #   @see Satisfactory::Record#to_plan
+    delegate :and, :create, :to_plan, to: :upstream
+
+    # Calls {#with} on each entry in the collection.
+    #
+    # @return [Satisfactory::Collection]
+    def with(...)
+      self.class.new(map { |entry| entry.with(...) }, upstream:)
+    end
+    alias each_with with
+
+    # Calls {#which_is} on each entry in the collection.
+    #
+    # @param (see Satisfactory::Record#which_is)
+    # @return [Satisfactory::Collection]
+    def which_are(...)
+      self.class.new(map { |entry| entry.which_is(...) }, upstream:)
+    end
+    alias which_is which_are
+
+    # (see Satisfactory::Record#and_same)
+    def and_same(upstream_type)
+      Satisfactory::UpstreamRecordFinder.new(upstream:).find(upstream_type)
+    end
+
+    # @api private
+    def build
+      flat_map(&:build)
+    end
+
+    # @api private
+    def build_plan
+      flat_map(&:build_plan)
+    end
+  end
+end

data/lib/satisfactory/loader.rb

@@ -0,0 +1,43 @@
+require "factory_bot_rails"
+
+module Satisfactory
+  # Loads factory configurations from FactoryBot.
+  #
+  # @api private
+  class Loader
+    class << self
+      # Skips factories that don't have a model that inherits from ApplicationRecord.
+      #
+      # @return [{Symbol => Hash}] a hash of factory configurations by factory name
+      def factory_configurations # rubocop:disable Metrics/AbcSize
+        FactoryBot.factories.each.with_object({}) do |(factory, model), configurations|
+          next unless (model = factory.build_class)
+          next unless model < ApplicationRecord
+
+          associations = associations_for(model)
+          parent_factory = factory.send(:parent)
+
+          configurations[factory.name] = {
+            associations: associations.transform_values { |a| a.map(&:name) },
+            model:,
+            name: factory.name,
+            parent: (parent_factory.name unless parent_factory.is_a?(FactoryBot::NullFactory)),
+            traits: factory.defined_traits.map(&:name),
+          }
+        end
+      end
+
+    private
+
+      def associations_for(model)
+        all = model.reflect_on_all_associations.reject(&:polymorphic?)
+        plural = model.reflect_on_all_associations(:has_many).reject(&:polymorphic?)
+
+        {
+          plural:,
+          singular: all - plural,
+        }
+      end
+    end
+  end
+end

data/lib/satisfactory/record.rb

@@ -0,0 +1,208 @@
+require_relative "collection"
+require_relative "upstream_record_finder"
+
+module Satisfactory
+  # Represents a usage of a type.
+  #
+  # @todo This whole class needs a tidy up
+  class Record # rubocop:disable Metrics/ClassLength
+    # @api private
+    # @param type [Symbol] The type of record to create.  Must be a known factory.
+    # @param factory_name [Symbol] The name of the factory to use (if different).
+    # @param upstream [Satisfactory::Record, Satisfactory::Collection, Satisfactory::Root] The upstream record-ish.
+    # @param attributes [Hash] The attributes to use when creating the record.
+    def initialize(type:, factory_name: nil, upstream: nil, attributes: {})
+      @factory_name = factory_name || type
+
+      config = Satisfactory.factory_configurations[type]
+      raise ArgumentError, "Unknown factory #{type}" unless config
+
+      @type = config[:parent] || type
+      @type_config = Satisfactory.factory_configurations[@type]
+      @traits = []
+      @upstream = upstream
+
+      @attributes = attributes
+
+      @associations = type_config.dig(:associations, :plural).each.with_object({}) do |name, hash|
+        hash[name] = Satisfactory::Collection.new(upstream: self)
+      end
+    end
+
+    # @api private
+    attr_accessor :type, :type_config, :traits, :upstream, :factory_name, :attributes
+
+    # Add an associated record to this record's build plan.
+    #
+    # @param count [Integer] The number of records to create.
+    # @param downstream_type [Symbol] The type of record to create.
+    # @param force [Boolean] Whether to force the creation of the record.
+    #   For internal use only.  Use {#and} instead.
+    # @param attributes [Hash] The attributes to use when creating the record.
+    # @return [Satisfactory::Record, Satisfactory::Collection]
+    def with(count = nil, downstream_type, force: false, **attributes) # rubocop:disable Style/OptionalArguments, Metrics/AbcSize, Metrics/MethodLength, Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
+      if singular?(downstream_type)
+        if count && count > 1 # rubocop:disable Style/IfUnlessModifier
+          raise ArgumentError, "Cannot create multiple of singular associations (e.g. belongs_to)"
+        end
+
+        add_singular_association(downstream_type, factory_name: downstream_type, force:, attributes:)
+      elsif plural?(downstream_type) && (singular = singular_from_plural(downstream_type))
+        add_plural_association(downstream_type, factory_name: singular, count:, force:, attributes:)
+      elsif (config = Satisfactory.factory_configurations[downstream_type])
+        singular = config[:parent] || downstream_type
+        plural = plural_from_singular(singular)
+        add_singular_for_plural_association(plural, singular:, factory_name: downstream_type, force:, attributes:)
+      elsif (config = Satisfactory.factory_configurations[downstream_type.to_s.singularize])
+        unless (parent = config[:parent])
+          raise ArgumentError, "Cannot create multiple of singular associations (e.g. belongs_to)"
+        end
+
+        plural = plural_from_singular(parent)
+        add_plural_association(plural, factory_name: downstream_type.to_s.singularize, count:, force:, attributes:)
+      else
+        raise ArgumentError, "Unknown association #{type}->#{downstream_type}"
+      end
+    end
+
+    # Add a sibling record to the parent record's build plan.
+    # e.g. adding a second user to a project.
+    #
+    # @param count [Integer] The number of records to create.
+    # @param downstream_type [Symbol] The type of record to create.
+    # @param attributes [Hash] The attributes to use when creating the record.
+    # @return (see #with)
+    def and(count = nil, downstream_type, **attributes) # rubocop:disable Style/OptionalArguments
+      upstream.with(count, downstream_type, force: true, **attributes)
+    end
+
+    # Apply one or more traits to this record's build plan.
+    #
+    # @param *traits [Symbol, ...] The traits to apply.
+    def which_is(*traits)
+      traits.each { |trait| self.traits << trait }
+      self
+    end
+
+    # Locate the nearest ancestor of the given type.
+    #
+    # @param upstream_type [Symbol] The type of ancestor to find.
+    # @return [Satisfactory::Record, Satisfactory::Collection, Satisfactory::Root]
+    def and_same(upstream_type)
+      Satisfactory::UpstreamRecordFinder.new(upstream:).find(upstream_type)
+    end
+
+    # @api private
+    def modify
+      yield(self).upstream
+    end
+
+    # Trigger the creation of this tree's build plan.
+    #
+    # @return (see Satisfactory::Root#create)
+    # @todo Check if we still need the upstream check.
+    def create
+      if upstream
+        upstream.create
+      else
+        create_self
+      end
+    end
+
+    # Construct this tree's build plan.
+    #
+    # @return [Hash]
+    def to_plan
+      if upstream
+        upstream.to_plan
+      else
+        build_plan
+      end
+    end
+
+    # @api private
+    def build_plan
+      {
+        traits:,
+      }.merge(associations_plan).compact_blank
+    end
+
+    # @api private
+    # @return (see #reify)
+    def build
+      reify(:build)
+    end
+
+    # @api private
+    # @return (see #reify)
+    def create_self
+      reify(:create)
+    end
+
+  private
+
+    attr_reader :associations
+
+    # @return [ApplicationRecord]
+    def reify(method)
+      FactoryBot.public_send(method, factory_name, *traits, attributes.merge(associations.transform_values(&:build)))
+    end
+
+    def associations_plan
+      associations.transform_values(&:build_plan).compact_blank
+    end
+
+    def plural?(association_name)
+      type_config.dig(:associations, :plural).include?(association_name)
+    end
+
+    def singular?(association_name)
+      type_config.dig(:associations, :singular).include?(association_name)
+    end
+
+    def plural_from_singular(singular_association_name)
+      type_config.dig(:associations, :plural).find do |name|
+        singular_association_name.to_s == name.to_s.singularize
+      end
+    end
+
+    def singular_from_plural(plural_association_name)
+      Satisfactory.factory_configurations.keys.find do |name|
+        plural_association_name.to_s == name.to_s.pluralize
+      end
+    end
+
+    def add_singular_association(name, factory_name:, force: false, attributes: {})
+      if force || associations[name].blank?
+        associations[name] = self.class.new(type: name, factory_name:, upstream: self, attributes:)
+      else
+        associations[name]
+      end
+    end
+
+    def add_plural_association(name, factory_name:, count: nil, force: false, attributes: {})
+      count ||= 1
+      singular_name = name.to_s.singularize.to_sym
+
+      Satisfactory::Collection.new(upstream: self).tap do |new_associations|
+        count.times do
+          new_associations << self.class.new(type: singular_name, factory_name:, upstream: self, attributes:)
+        end
+
+        if force
+          associations[name] << new_associations
+        else
+          associations[name] = new_associations
+        end
+      end
+    end
+
+    def add_singular_for_plural_association(name, singular:, factory_name:, force: false, attributes: {})
+      if force || associations[name].empty?
+        associations[name] << self.class.new(type: singular, factory_name:, upstream: self, attributes:)
+      end
+
+      associations[name].last
+    end
+  end
+end

data/lib/satisfactory/root.rb

@@ -0,0 +1,47 @@
+require_relative "record"
+
+module Satisfactory
+  # The root of the factory graph.
+  # This is where you begin creating records.
+  class Root
+    # @api private
+    def initialize
+      @root_records = Hash.new { |h, k| h[k] = [] }
+    end
+
+    # Add a top-level record to the root.
+    # This is your entry point into the factory graph, and
+    # the way to begin creating records.
+    def add(factory_name, **attributes)
+      raise FactoryNotDefinedError, factory_name unless Satisfactory.factory_configurations.key?(factory_name)
+
+      Satisfactory::Record.new(
+        type: factory_name,
+        upstream: self,
+        attributes:,
+      ).tap { |r| @root_records[factory_name] << r }
+    end
+
+    # @api private
+    # @return [Hash<Symbol, Array<ApplicationRecord>>]
+    def create
+      @root_records.transform_values do |records|
+        records.map(&:create_self)
+      end
+    end
+
+    # @api private
+    # @return [Hash<Symbol, Array<Hash>>]
+    def to_plan
+      @root_records.transform_values do |records|
+        records.map(&:build_plan)
+      end
+    end
+
+    # @api private
+    # @return [nil]
+    def upstream
+      nil
+    end
+  end
+end

data/lib/satisfactory/upstream_record_finder.rb

@@ -0,0 +1,30 @@
+module Satisfactory
+  # Finds the upstream record of a given type.
+  #
+  # @api private
+  class UpstreamRecordFinder
+    def initialize(upstream:)
+      @upstream = upstream
+    end
+
+    attr_accessor :upstream
+
+    def find(type)
+      raise MissingUpstreamRecordError, type if upstream.nil?
+
+      if type == upstream.type
+        self
+      else
+        self.upstream = upstream.upstream
+        find(type)
+      end
+    end
+
+    def with(*args, **kwargs)
+      upstream.with(*args, force: true, **kwargs)
+    end
+
+    # @api private
+    class MissingUpstreamRecordError < StandardError; end
+  end
+end

data/lib/satisfactory/version.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module Satisfactory
-  VERSION = "0.0.0"
+  VERSION = "0.2.1".freeze
 end

data/lib/satisfactory.rb

@@ -1,8 +1,24 @@
-# frozen_string_literal: true
-
-require_relative "satisfactory/version"
+require_relative "satisfactory/loader"
+require_relative "satisfactory/root"
 
+# Satisfactory is a factory library for Ruby,
+# helping you to navigate your factory associations.
+#
+# Currently implemented atop FactoryBot, but
+# could be extended to support other factory libraries.
+#
+# @since 0.2.0
 module Satisfactory
-  class Error < StandardError; end
-  # Your code goes here...
+  # @!attribute [r] factory_configurations
+  class << self
+    def root
+      Root.new
+    end
+
+    # @api private
+    # @return (see Loader.factory_configurations)
+    def factory_configurations
+      @factory_configurations ||= Loader.factory_configurations
+    end
+  end
 end

data/satisfactory.gemspec

@@ -0,0 +1,37 @@
+require_relative "lib/satisfactory/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "satisfactory"
+  spec.version = Satisfactory::VERSION
+  spec.authors = ["Elliot Crosby-McCullough"]
+  spec.email = ["elliot.cm@gmail.com"]
+
+  spec.summary = "A DSL for navigating your factories and building test data"
+  spec.homepage = "https://github.com/SmartCasual/satisfactory"
+  spec.license = "CC-BY-NC-SA-4.0"
+
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/v#{spec.version}/CHANGELOG.md"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  spec.metadata["rubygems_mfa_required"] = "true"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) {
+    Dir[
+      "lib/**/*",
+      "CHANGELOG.md",
+      "LICENCE",
+      "Rakefile",
+      "README.md",
+      "satisfactory.gemspec",
+    ]
+  }
+
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "factory_bot_rails", "~> 6.2"
+
+  spec.add_development_dependency "rubocop", "~> 1.40"
+  spec.add_development_dependency "yard", "~> 0.9"
+end

metadata

@@ -1,15 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: satisfactory
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Elliot Crosby-McCullough
 autorequire:
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2022-12-09 00:00:00.000000000 Z
-dependencies: []
+date: 2022-12-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: factory_bot_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.2'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.40'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.40'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description:
 email:
 - elliot.cm@gmail.com
@@ -17,19 +59,26 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".rubocop.yml"
 - CHANGELOG.md
-- Gemfile
+- LICENCE
 - README.md
 - Rakefile
 - lib/satisfactory.rb
+- lib/satisfactory/collection.rb
+- lib/satisfactory/loader.rb
+- lib/satisfactory/record.rb
+- lib/satisfactory/root.rb
+- lib/satisfactory/upstream_record_finder.rb
 - lib/satisfactory/version.rb
-- sig/satisfactory.rbs
+- satisfactory.gemspec
 homepage: https://github.com/SmartCasual/satisfactory
-licenses: []
+licenses:
+- CC-BY-NC-SA-4.0
 metadata:
+  changelog_uri: https://github.com/SmartCasual/satisfactory/blob/v0.2.1/CHANGELOG.md
   homepage_uri: https://github.com/SmartCasual/satisfactory
   source_code_uri: https://github.com/SmartCasual/satisfactory
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -38,7 +87,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -48,5 +97,5 @@ requirements: []
 rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
-summary: Write a short summary, because RubyGems requires one.
+summary: A DSL for navigating your factories and building test data
 test_files: []

data/.rubocop.yml

@@ -1,13 +0,0 @@
-AllCops:
-  TargetRubyVersion: 2.6
-
-Style/StringLiterals:
-  Enabled: true
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  Enabled: true
-  EnforcedStyle: double_quotes
-
-Layout/LineLength:
-  Max: 120

data/Gemfile

@@ -1,10 +0,0 @@
-# frozen_string_literal: true
-
-source "https://rubygems.org"
-
-# Specify your gem's dependencies in satisfactory.gemspec
-gemspec
-
-gem "rake", "~> 13.0"
-
-gem "rubocop", "~> 1.21"

data/sig/satisfactory.rbs

@@ -1,4 +0,0 @@
-module Satisfactory
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end