foundries 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a0ecd2813e2ccbe57b1889f98748c0590d208e83005b32fb0302004b8c31b708
+  data.tar.gz: 82dd0fe2b8f3fee39e3eb6821fb2fd3e2c222cebd599c4d6a0cd898b3af780f6
+SHA512:
+  metadata.gz: 8585abf3336113d8ba508a67b9b83c207f7e3de3deeeb251f34cd1ba2449e9f62928e73b8e0f350205438f4284f0e07df59ac15456305fb8088d66febff6d738
+  data.tar.gz: 02db8e30a432fddd54df80e32aa801bea689660bd252746ab3b79bc3a04e6bccf9cc75eed9c0977641ff37be25bce1237325bed770c457ca78225ec073d692bb

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+## [0.1.0] - 2026-02-25

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 SOFware LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,249 @@
+# Foundries
+
+Declarative trees of related records using factory_bot.
+
+Foundries composes factory_bot factories into **blueprints** that know how to create, find, and relate records. You register blueprints with a **base** class, then build entire object graphs with a nested DSL:
+
+```ruby
+TestFoundry.new do
+  team "Engineering" do
+    user "Alice"
+    admin "Bob"
+
+    project "API" do
+      task "Auth", priority: "high"
+      task "Caching"
+    end
+  end
+end
+```
+
+Each method call creates a record (or finds an existing one), and nesting establishes parent-child context automatically. No manual foreign key wiring.
+
+## Installation
+
+```ruby
+gem "foundries"
+```
+
+## Usage
+
+### Blueprints
+
+A blueprint wraps a single factory_bot factory and declares how it participates in the tree:
+
+```ruby
+class TeamBlueprint < Foundries::Blueprint
+  handles :team
+  factory :team
+  collection :teams
+  parent :none
+  permitted_attrs %i[name]
+
+  def team(name, attrs = {}, &block)
+    @attrs = attrs.merge(name: name)
+    object = find(name) || create_object
+    update_state_for_block(object, &block) if block
+    object
+  ensure
+    reset_attrs
+  end
+
+  private
+
+  def create_object
+    create(:team, attrs).tap { |record| collection << record }
+  end
+
+  def attrs
+    permitted_attrs @attrs
+  end
+end
+```
+
+#### Blueprint DSL
+
+| Method | Purpose |
+|--------|---------|
+| `handles :method_name` | Methods this blueprint exposes on the foundry |
+| `factory :name` | Which factory_bot factory to use (inferred from class name if omitted) |
+| `collection :name` | Collection name for tracking created records |
+| `parent :name` | How to find the parent record (`:none`, `:self`, or a method on `current`) |
+| `parent_key :foreign_key` | Foreign key column linking to the parent |
+| `permitted_attrs %i[...]` | Attributes allowed through to factory_bot |
+| `nested_attrs key => [...]` | For `accepts_nested_attributes_for` |
+
+#### Finding records
+
+Blueprints automatically prevent duplicates. `find(name)` checks the in-memory collection first, then falls back to the database. `find_by(criteria)` works with arbitrary attributes.
+
+#### Parent context
+
+When a block is passed to a blueprint method, `update_state_for_block` saves the current context, sets the new record as `current.resource`, executes the block, then restores the previous context. Child blueprints read their parent from `current`:
+
+```ruby
+class UserBlueprint < Foundries::Blueprint
+  handles :user
+  parent :team         # reads current.team
+  parent_key :team_id  # sets team_id on created records
+  # ...
+end
+```
+
+### Base (the foundry)
+
+Register blueprints and optional extra collections:
+
+```ruby
+class TestFoundry < Foundries::Base
+  blueprint TeamBlueprint
+  blueprint UserBlueprint
+  blueprint ProjectBlueprint
+  blueprint TaskBlueprint
+
+  collection :tags  # extra collection not from a blueprint
+end
+```
+
+The base class:
+
+- Instantiates each blueprint and delegates its `handles` methods
+- Initializes a `Set` for each collection (e.g. `teams_collection`)
+- Tracks `current` state so nested blocks know their parent context
+- Deduplicates records via each blueprint's `find` logic
+
+### Presets
+
+Presets are named class methods that build a preconfigured foundry:
+
+```ruby
+class TestFoundry < Foundries::Base
+  # ...
+
+  preset :dev_team do
+    team "Engineering" do
+      user "Alice"
+      project "Main" do
+        task "Setup"
+      end
+    end
+  end
+end
+
+# In a test:
+let(:foundry) { TestFoundry.dev_team }
+```
+
+### Reopening
+
+Add more records to an existing foundry:
+
+```ruby
+foundry = TestFoundry.dev_team
+foundry.reopen do
+  team "Design" do
+    user "Carol"
+  end
+end
+```
+
+### Building from existing objects
+
+Start from records already in the database:
+
+```ruby
+foundry = TestFoundry.new
+foundry.from(existing_team) do
+  user "New hire"
+end
+```
+
+### Lifecycle hooks
+
+Override `setup` and `teardown` in your base subclass for pre/post processing:
+
+```ruby
+class TestFoundry < Foundries::Base
+  private
+
+  def setup
+    @pending_rules = []
+  end
+
+  def teardown
+    process_pending_rules
+  end
+end
+```
+
+## Snapshot Caching
+
+When using ActiveRecord, Foundries can snapshot preset data to disk and restore it instead of re-running factories. This is useful for speeding up test suites where the same preset is called many times.
+
+Enable with an environment variable:
+
+```
+FOUNDRIES_CACHE=1 bundle exec rspec
+```
+
+Or configure directly:
+
+```ruby
+Foundries::Snapshot.enabled = true
+Foundries::Snapshot.storage_path = "tmp/foundries"  # default
+Foundries::Snapshot.source_paths = [
+  "lib/blueprints/**/*.rb",
+  "lib/test_foundry.rb"
+]
+```
+
+Snapshots are invalidated automatically when the schema version changes or when source files listed in `source_paths` are modified. Data is captured using database-native copy operations (PostgreSQL `COPY`, SQLite `INSERT`) and restored with referential integrity checks temporarily disabled.
+
+## Similarity Detection
+
+Foundries can detect when presets have overlapping structure, highlighting consolidation opportunities. When enabled, it records the normalized blueprint call tree of each preset and compares against previously seen presets.
+
+Enable with an environment variable:
+
+```
+FOUNDRIES_SIMILARITY=1 bundle exec rspec
+```
+
+Or configure directly:
+
+```ruby
+Foundries::Similarity.enabled = true
+```
+
+When two presets share identical structure or one is structurally contained within another, a warning is printed to stderr:
+
+```
+[Foundries] Preset :basic and :extended have identical structure (team > [project > [task], user])
+[Foundries] Preset :simple is structurally contained within :complex
+```
+
+Each unique pair is warned once per process. The detection normalizes trees by deduplicating sibling nodes (keeping the richest subtree), collapsing pass-through chains, and sorting alphabetically. This means presets that build the same *shape* of data are detected regardless of the specific names or attribute values used.
+
+## Requirements
+
+- Ruby >= 4.0
+- factory_bot >= 6.0
+- ActiveRecord (optional, for snapshot caching)
+
+## License
+
+MIT
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rake` to run the tests.
+
+To install this gem onto your local machine, run bundle exec rake install.
+
+This project is managed with [Reissue](https://github.com/SOFware/reissue).
+
+Releases are automated via the [shared release workflow](https://github.com/SOFware/reissue/blob/main/.github/workflows/SHARED_WORKFLOW_README.md). Trigger a release by running the "Release gem to RubyGems.org" workflow from the Actions tab.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/SOFware/foundries.

data/Rakefile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]
+
+require "reissue/gem"
+
+Reissue::Task.create :reissue do |task|
+  task.version_file = "lib/foundries/version.rb"
+  task.fragment = :git
+end

data/lib/foundries/base.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require "ostruct"
+
+module Foundries
+  # Base is the orchestrator that composes multiple Blueprints into a single
+  # declarative builder for trees of related records.
+  #
+  # Subclass Base and declare which blueprints it uses:
+  #
+  #   class MyFoundry < Foundries::Base
+  #     blueprint UserBlueprint
+  #     blueprint ProjectBlueprint
+  #
+  #     # Optional: additional collections beyond what blueprints declare
+  #     collection :tags
+  #   end
+  #
+  #   MyFoundry.new do
+  #     user "Alice" do
+  #       project "Widget" do
+  #         # ...
+  #       end
+  #     end
+  #   end
+  #
+  class Base
+    include FactoryBot::Syntax::Methods
+
+    class << self
+      attr_accessor :_active_similarity_recorder
+
+      # Register a blueprint class with this foundry.
+      def blueprint(klass)
+        blueprint_registry[klass] = klass.handled_methods
+      end
+
+      # All registered blueprint classes and their handled methods.
+      def blueprint_registry
+        @blueprint_registry ||= {}
+      end
+
+      # Declare additional collection names beyond those from blueprints.
+      def collection(*names)
+        extra_collections.concat(names.map(&:to_s))
+      end
+
+      def extra_collections
+        @extra_collections ||= []
+      end
+
+      # All collection accessor names (e.g. "users_collection").
+      def collection_accessors
+        (blueprint_collection_names + extra_collections).map { |name| "#{name}_collection" }
+      end
+
+      # Collection names derived from blueprint declarations.
+      def blueprint_collection_names
+        blueprint_registry.keys.filter_map { |klass| klass.collection_name&.to_s }
+      end
+
+      # Methods delegated from this foundry to its blueprint instances.
+      def delegations
+        blueprint_registry.select { |_, methods| methods.any? }
+      end
+
+      # Define presets — named class methods that build a preconfigured foundry.
+      #
+      #   class MyFoundry < Foundries::Base
+      #     preset :full_team do
+      #       user "Alice"
+      #       user "Bob"
+      #     end
+      #   end
+      #
+      #   MyFoundry.full_team  # => configured foundry instance
+      #
+      def preset(name, &block)
+        define_singleton_method(name) do
+          with_similarity_recording(name, Similarity.enabled?) do
+            if defined?(Foundries::Snapshot) && Foundries::Snapshot.enabled?
+              store = Foundries::Snapshot::Store.new(name)
+
+              if store.cached?
+                store.restore
+                next new # hollow — no block, data already in DB
+              end
+
+              store.record_empty_tables
+              foundry = new(&block)
+              store.capture
+              foundry
+            else
+              new(&block)
+            end
+          end
+        end
+      end
+
+      def with_similarity_recording(preset_name, recording)
+        if recording
+          self._active_similarity_recorder = Similarity::Recorder.new
+          foundry = yield
+          tree = _active_similarity_recorder.normalized_tree
+          self._active_similarity_recorder = nil
+
+          key = "#{name}.#{preset_name}"
+          warnings = Similarity::Comparator.compare(key, tree, Similarity.registry)
+          warnings.each do |w|
+            next unless Similarity.warned_pairs.add?(w[:pair])
+            warn w[:message]
+          end
+          Similarity.registry[key] = tree
+          foundry
+        else
+          yield
+        end
+      end
+
+      def inherited(subclass)
+        super
+        # Ensure subclasses get their own registries
+        subclass.instance_variable_set(:@blueprint_registry, {})
+        subclass.instance_variable_set(:@extra_collections, [])
+      end
+    end
+
+    def initialize(&block)
+      @_similarity_recorder = self.class._active_similarity_recorder
+      instantiate_blueprints
+      initialize_collections
+      @current = OpenStruct.new(resource: self)
+      setup
+      instance_exec(&block) if block
+      teardown
+      @current.resource = nil
+    end
+
+    attr_accessor :current
+
+    # Reopen the foundry to add more records.
+    def reopen(&block)
+      @current = OpenStruct.new(resource: self)
+      instance_exec(&block) if block
+      teardown
+      @current.resource = nil
+      self
+    end
+
+    # Build within the context of existing objects.
+    def from(objects, &block)
+      execute_and_restore_state do
+        load_existing_objects(objects)
+        instance_exec(&block) if block
+        teardown
+      end
+    end
+
+    def load_existing_objects(objects)
+      return if objects.nil? || (objects.respond_to?(:empty?) && objects.empty?)
+
+      Array(objects).each do |object|
+        load_state(object)
+
+        klass_name = object.class.name
+        blueprint_class = find_blueprint_class_for(klass_name)
+        next unless blueprint_class
+
+        blueprint_class.load_state_from(object, self)
+      end
+    end
+
+    def execute_and_restore_state
+      initial_state = @current.dup
+      yield.tap { @current = initial_state }
+    end
+
+    def load_state(object)
+      klass_name = object.class.name.underscore.tr("/", "_")
+      current.send(:"#{klass_name}=", object)
+      collection_name = "#{klass_name.pluralize}_collection"
+      return unless respond_to?(collection_name)
+
+      send(collection_name) << object
+    end
+    alias_method :update_current, :load_state
+
+    private
+
+    # Override in subclasses for post-initialize hooks (e.g. pending phase rules).
+    def setup
+    end
+
+    # Override in subclasses for post-block hooks (e.g. processing pending items).
+    def teardown
+    end
+
+    def instantiate_blueprints
+      self.class.blueprint_registry.each_key do |klass|
+        ivar = :"@#{ivar_name_for(klass)}"
+        instance_variable_set(ivar, klass.new(self))
+      end
+
+      # Set up delegation from foundry methods to blueprint instances
+      self.class.delegations.each do |klass, methods|
+        ivar = :"@#{ivar_name_for(klass)}"
+        blueprint_instance = instance_variable_get(ivar)
+        methods.each do |method_name|
+          define_singleton_method(method_name) do |*args, **kwargs, &block|
+            blueprint_instance.send(method_name, *args, **kwargs, &block)
+          end
+        end
+      end
+    end
+
+    def initialize_collections
+      self.class.collection_accessors.each do |col|
+        instance_variable_set(:"@#{col}", Set.new)
+        # Define accessor if not already defined
+        define_singleton_method(col) { instance_variable_get(:"@#{col}") }
+        define_singleton_method(:"#{col}=") { |val| instance_variable_set(:"@#{col}", val) }
+      end
+    end
+
+    def ivar_name_for(klass)
+      klass.name.demodulize.underscore
+    end
+
+    def find_blueprint_class_for(model_class_name)
+      self.class.blueprint_registry.keys.detect do |klass|
+        klass.name.demodulize.delete_suffix("Blueprint") == model_class_name
+      end
+    end
+  end
+end