satisfactory 0.3.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb0881c675798a625a5af2ba2837a9689191df29051a54c12f3e0f6e38a948d7
-  data.tar.gz: cfe749028066a66f517679c6132e6d5a884b673e4bf5f3c329aadc4cb43acaf4
+  metadata.gz: 65c8d9c40c194cb99ea20abed50386c82150e1474a3b82089a2c9d14948ccc3c
+  data.tar.gz: 568fdc7b04e1d89f26e5832f61b406dd54e3c501c1cfcf35586cddcfb25e829a
 SHA512:
-  metadata.gz: 87e998bfc2817381695b8b16a212fe5d328db770549613dbe962406574446f8017f77d068f5ea447df97b2abe75710662544500fae9728855e167c3915b6b737
-  data.tar.gz: 442023301434a224e7b3b71f36762a21432ef681cdf9951672286c6377454649aa4fea7abd8f3e93e5de79f17587f0cc0c8f7e1398c61239dc6f6dc0dedc85ab
+  metadata.gz: 25f309d08266688c528b1ce09a9830b17219d74402ef168a4ba77f88ee8234822be463426db03fcd1e1e7ddb24940ea0d55b1a4a35604ced4eeac24c7984155f
+  data.tar.gz: ee0a8f3615eaaa8f9578e770703c8819297c7eb0a75f9f4332168c4522e1510b8bd66e7bf66a7071b95895a5b012f7dfd1b54ec11aa729af2a1e47ae42f1df7a

data/CHANGELOG.md

@@ -1,4 +1,24 @@
-## [Unreleased]
+## [1.0.0] - 2026-06-11
+
+- Require Ruby >= 3.2, dropping end-of-life Ruby 3.1
+- Update the development toolchain to Ruby 3.4, Rails 8.0, RSpec 3.13, rspec-rails 7.0, and the latest RuboCop
+- Replace the `byebug` development dependency with `debug`
+- Run the RSpec suite as part of the default Rake task (and in CI), not just RuboCop
+- Load the dummy app's schema automatically when running the suite
+- Share a single Gemfile between the gem and its dummy test app
+- Refresh the bundle for current platforms (Apple Silicon and Linux)
+- Replace the boilerplate README with real installation and usage instructions
+- Add a Rails-free unit suite characterising `Record`, `Collection`, `Root`, and `UpstreamRecordFinder`, plus a `Loader` spec
+- Depend on `factory_bot` and `activesupport` directly instead of `factory_bot_rails`, so the gem no longer pulls in a Railtie
+- Refactor `Record#with` into a small classifier plus focused helpers, removing all of its RuboCop disables
+- `Record#with(2, :racing_wheels)` (the plural of an STI child type) now works instead of raising "Unknown association"; the plural of a parentless singular now raises the clearer "Cannot create multiple of singular associations" error
+- Include provided attributes in the output of `#to_plan` / `#build_plan`
+- Show every association that was explicitly added in the build plan (including empty singular associations), rather than silently dropping empties
+- Drop the unused `model`, `name`, and `traits` fields from loaded factory configurations
+
+## [0.3.2] - 2023-01-24
+
+- Add some missing proxy methods
 
 ## [0.3.1] - 2023-01-18
 

data/README.md

@@ -1,29 +1,96 @@
 # Satisfactory
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/satisfactory`. To experiment with that code, run `bin/console` for an interactive prompt.
+Satisfactory is a factory library for Ruby that helps you navigate your factory
+associations and build trees of test data with a fluent, readable DSL.
 
-TODO: Delete this and the text above, and describe your gem
+It is currently implemented on top of
+[FactoryBot](https://github.com/thoughtbot/factory_bot), but could be extended to
+support other factory libraries.
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+Install the gem and add it to the application's Gemfile by executing:
 
-    $ bundle add satisfactory
+```sh
+bundle add satisfactory
+```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install satisfactory
+```sh
+gem install satisfactory
+```
+
+Satisfactory reads your existing FactoryBot factories. Only factories whose model
+inherits from `ApplicationRecord` are picked up.
 
 ## Usage
 
-TODO: Write usage instructions here
+Start from the root and describe the tree of records you want, then call `create`
+to build it (or `to_plan` to inspect what would be built):
+
+```ruby
+Satisfactory.root
+  .add(:candidate, email_address: "sample@example.com")
+  .with(:application_form).which_is(:submitted)
+  .with(:application_choice)
+  .and(2, :application_choices)
+  .each_with(:course_option).which_is(:part_time)
+  .and_same(:candidate)
+  .with(:application_form, first_name: "Jane")
+  .with(:application_choice).which_is(:rejected)
+  .create
+```
+
+### The DSL
+
+- `Satisfactory.root` — the entry point into the factory graph.
+- `add(:factory, **attributes)` — add a top-level record to the root.
+- `with(count = nil, :association, **attributes)` — add an associated record (or
+  `count` of them for plural associations) to the current record.
+- `with_new(count = nil, :association, **attributes)` — like `with`, but always
+  creates a new record rather than reusing an existing one.
+- `and(count = nil, :association, **attributes)` — add a sibling record to the
+  current record's parent (e.g. a second `application_form` on the same candidate).
+- `which_is(*traits)` / `which_are(*traits)` — apply one or more FactoryBot traits
+  to the current record(s).
+- `each_with(...)` / `which_are(...)` — operate on every record in a collection.
+- `and_same(:type)` (aliased as `return_to`) — walk back up the tree to the nearest
+  ancestor of the given type to continue building from there.
+- `create` — build the whole tree and persist it. Returns the created records.
+- `to_plan` — return a hash describing what would be built, without persisting.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies.
+
+The test suite exercises a dummy Rails application backed by PostgreSQL, so you'll
+need a running PostgreSQL server. Create the test database once with:
+
+```sh
+createdb satisfactory_dummy_test
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Then run the default task, which runs both the specs and RuboCop:
+
+```sh
+bin/rake
+```
+
+You can also run them individually with `bin/rspec` and `bin/rubocop`, or open an
+interactive prompt with `bin/console`.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push git
+commits and the created tag, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/satisfactory.
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/SmartCasual/satisfactory.
+
+## Licence
+
+Released under the [CC-BY-NC-SA-4.0](LICENCE) licence.

data/lib/satisfactory/collection.rb

@@ -1,11 +1,13 @@
+require "active_support/core_ext/module/delegation"
+
 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)
+    def initialize(*, upstream:, **, &)
+      super(*, **, &)
       @upstream = upstream
     end
 
@@ -47,6 +49,7 @@ module Satisfactory
     def and_same(upstream_type)
       Satisfactory::UpstreamRecordFinder.new(upstream:).find(upstream_type)
     end
+    alias return_to and_same
 
     # @api private
     def build

data/lib/satisfactory/loader.rb

@@ -1,4 +1,4 @@
-require "factory_bot_rails"
+require "factory_bot"
 
 module Satisfactory
   # Loads factory configurations from FactoryBot.
@@ -9,26 +9,26 @@ module Satisfactory
       # 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|
+      def factory_configurations
+        FactoryBot.factories.each.with_object({}) do |factory, 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),
-          }
+          configurations[factory.name] = configuration_for(factory, model)
         end
       end
 
     private
 
+      def configuration_for(factory, model)
+        parent_factory = factory.send(:parent)
+
+        {
+          associations: associations_for(model).transform_values { |a| a.map(&:name) },
+          parent: (parent_factory.name unless parent_factory.is_a?(FactoryBot::NullFactory)),
+        }
+      end
+
       def associations_for(model)
         all = model.reflect_on_all_associations.reject(&:polymorphic?)
         plural = model.reflect_on_all_associations(:has_many).reject(&:polymorphic?)

data/lib/satisfactory/record.rb

@@ -1,10 +1,12 @@
+require "active_support/core_ext/enumerable"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/string/inflections"
+
 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.
@@ -30,7 +32,7 @@ module Satisfactory
     end
 
     # @api private
-    attr_accessor :type, :type_config, :traits, :upstream, :factory_name, :attributes
+    attr_reader :type, :type_config, :traits, :upstream, :factory_name, :attributes
 
     # Add an associated record to this record's build plan.
     #
@@ -40,26 +42,16 @@ module Satisfactory
     #   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:)
+    def with(*arguments, force: false, **attributes)
+      count, downstream_type = parse_with_arguments(arguments)
+
+      case association_kind(downstream_type)
+      when :singular then add_singular(downstream_type, count:, force:, attributes:)
+      when :plural then add_plural(downstream_type, count:, force:, attributes:)
+      when :child then add_child(downstream_type, force:, attributes:)
+      when :child_collection then add_child_collection(downstream_type, count:, force:, attributes:)
+      when :singular_collection
+        raise ArgumentError, "Cannot create multiple of singular associations (e.g. belongs_to)"
       else
         raise ArgumentError, "Unknown association #{type}->#{downstream_type}"
       end
@@ -69,8 +61,8 @@ module Satisfactory
     #
     # @param (see #and)
     # @return (see #with)
-    def with_new(count = nil, downstream_type, **attributes) # rubocop:disable Style/OptionalArguments
-      with(count, downstream_type, force: true, **attributes)
+    def with_new(*, **attributes)
+      with(*, force: true, **attributes)
     end
 
     # Add a sibling record to the parent record's build plan.
@@ -80,8 +72,8 @@ module Satisfactory
     # @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)
+    def and(*, **attributes)
+      upstream.with(*, force: true, **attributes)
     end
 
     # Apply one or more traits to this record's build plan.
@@ -104,7 +96,6 @@ module Satisfactory
     # 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
@@ -126,9 +117,9 @@ module Satisfactory
 
     # @api private
     def build_plan
-      {
-        traits:,
-      }.merge(associations_plan).compact_blank
+      plan = associations_plan
+      plan[:traits] = traits if traits.any?
+      plan.merge(attributes)
     end
 
     # @api private
@@ -152,8 +143,60 @@ module Satisfactory
       FactoryBot.public_send(method, factory_name, *traits, provided_associations.merge(attributes))
     end
 
+    # Split the variadic positional arguments to {#with} into an optional count
+    # and the downstream type.  Supports `with(:type)` and `with(2, :types)`.
+    def parse_with_arguments(arguments)
+      *count, downstream_type = arguments
+      [count.first, downstream_type]
+    end
+
+    # Classify how +downstream_type+ relates to this record.
+    #
+    # @return [Symbol] one of +:singular+, +:plural+, +:child+,
+    #   +:child_collection+, +:singular_collection+ or +:unknown+.
+    def association_kind(downstream_type)
+      return :singular if singular?(downstream_type)
+      return :plural if plural?(downstream_type) && singular_from_plural(downstream_type)
+      return :child if Satisfactory.factory_configurations.key?(downstream_type)
+
+      config = Satisfactory.factory_configurations[downstream_type.to_s.singularize.to_sym]
+      return :unknown unless config
+
+      config[:parent] ? :child_collection : :singular_collection
+    end
+
+    def add_singular(downstream_type, count:, force:, attributes:)
+      raise ArgumentError, "Cannot create multiple of singular associations (e.g. belongs_to)" if count && count > 1
+
+      add_singular_association(downstream_type, factory_name: downstream_type, force:, attributes:)
+    end
+
+    def add_plural(downstream_type, count:, force:, attributes:)
+      singular = singular_from_plural(downstream_type)
+      add_plural_association(downstream_type, factory_name: singular, count:, force:, attributes:)
+    end
+
+    def add_child(downstream_type, force:, attributes:)
+      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:)
+    end
+
+    def add_child_collection(downstream_type, count:, force:, attributes:)
+      singular = downstream_type.to_s.singularize.to_sym
+      parent = Satisfactory.factory_configurations[singular][:parent]
+      plural = plural_from_singular(parent)
+      add_plural_association(plural, factory_name: singular, count:, force:, attributes:)
+    end
+
     def associations_plan
-      associations.transform_values(&:build_plan).compact_blank
+      associations.each_with_object({}) do |(name, association), plan|
+        sub_plan = association.build_plan
+        next if plural?(name) && sub_plan.empty?
+
+        plan[name] = sub_plan
+      end
     end
 
     def plural?(association_name)

data/lib/satisfactory/upstream_record_finder.rb

@@ -1,3 +1,5 @@
+require "active_support/core_ext/module/delegation"
+
 module Satisfactory
   # Finds the upstream record of a given type.
   #
@@ -18,7 +20,11 @@ module Satisfactory
     #   Delegates to the upstream record.
     #   @return (see Satisfactory::Record#with_new)
     #   @see Satisfactory::Record#with_new
-    delegate :create, :with_new, to: :upstream
+    # @!method to_plan
+    #   Delegates to the upstream record.
+    #   @return (see Satisfactory::Record#with_new)
+    #   @see Satisfactory::Record#with_new
+    delegate :create, :with_new, :to_plan, to: :upstream
 
     # Find the upstream record of the given type.
     #
@@ -37,8 +43,8 @@ module Satisfactory
     end
 
     # (see Satisfactory::Record#with)
-    def with(*args, **kwargs)
-      upstream.with(*args, force: true, **kwargs)
+    def with(*, **)
+      upstream.with(*, force: true, **)
     end
 
     # @api private

data/lib/satisfactory/version.rb

@@ -1,3 +1,3 @@
 module Satisfactory
-  VERSION = "0.3.1".freeze
+  VERSION = "1.0.0".freeze
 end

data/satisfactory.gemspec

@@ -15,9 +15,9 @@ Gem::Specification.new do |spec|
   spec.metadata["source_code_uri"] = spec.homepage
 
   spec.metadata["rubygems_mfa_required"] = "true"
-  spec.required_ruby_version = ">= 3.1.0"
+  spec.required_ruby_version = ">= 3.2.0"
 
-  spec.files = Dir.chdir(File.expand_path(__dir__)) {
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
     Dir[
       "lib/**/*",
       "CHANGELOG.md",
@@ -25,9 +25,10 @@ Gem::Specification.new do |spec|
       "README.md",
       "satisfactory.gemspec",
     ]
-  }
+  end
 
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "factory_bot_rails", "~> 6.2"
+  spec.add_dependency "activesupport", ">= 7.1"
+  spec.add_dependency "factory_bot", "~> 6.4"
 end

metadata

@@ -1,30 +1,42 @@
 --- !ruby/object:Gem::Specification
 name: satisfactory
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Elliot Crosby-McCullough
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-01-18 00:00:00.000000000 Z
+date: 2026-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: factory_bot_rails
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: factory_bot
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.2'
+        version: '6.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.2'
-description:
+        version: '6.4'
 email:
 - elliot.cm@gmail.com
 executables: []
@@ -46,11 +58,10 @@ homepage: https://github.com/SmartCasual/satisfactory
 licenses:
 - CC-BY-NC-SA-4.0
 metadata:
-  changelog_uri: https://github.com/SmartCasual/satisfactory/blob/v0.3.1/CHANGELOG.md
+  changelog_uri: https://github.com/SmartCasual/satisfactory/blob/v1.0.0/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:
 - lib
@@ -58,15 +69,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: A DSL for navigating your factories and building test data
 test_files: []