foundries 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8245b09fe2227ef4a25d5751c30f4a94a1d2d80519ef5fb97b8ba2b9dc527ef
-  data.tar.gz: 24162154115e9f413117fb88d71aa0cbc19374cbbf9b6fa059f23e36535511e5
+  metadata.gz: ee65151ab0ae7d4ef338d8dd8dec76fbf9f0746be24d99d814abdee8716c500a
+  data.tar.gz: 9a298a3ca012affe264f0467240f7a44b46decb2227f88f9eb2ca27c28f8bfad
 SHA512:
-  metadata.gz: f0b22d20d6edc795ef1c7a2f3403b1a7e5cbbbc0d3ca4bd19fc82c25992bcea6d460175df202d8cd0465dd328a8bc189672171423ed283aa7879390450261318
-  data.tar.gz: 1ece80e18cdc964013db346ec665e2919f146bda411ddaf4254abb4c714c712a4a692cb30241a051da98029c164fbbc77b1e4fc44c2dac0cadda396c0fbccadf
+  metadata.gz: 3b0eef54e2302dbda0dcc4ee7a9224c75e31f90b42498dabcdcac4a8e00318bc79bd34f343367cd2f03ab1cb969f72b01d4336c49ae4329eac5d7ebd136b64c1
+  data.tar.gz: 60f6748284f995381cc16f26a816f7f1ac9fac581948bbd0bc553c4839caf4cd9df6634982930d9017f896bdbb8d5f3edd3072aca7be19f5b9ba1620479c3a27

data/CHANGELOG.md

@@ -5,22 +5,19 @@ 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.3] - 2026-03-13
+## [0.1.4] - 2026-03-16
 
 ### Added
 
-- ancestor DSL and ancestors_for for path-based hierarchy building (7027e06)
+- Recording module to analyze FactoryBot usage and suggest preset candidates (a294324)
+- parallel_tests support for Recording with per-worker output and merge rake task (8e59deb)
 
-## [0.1.2] - 2026-03-12
+### Changed
 
-### Added
+- README now covers Recording feature and parallel_tests support (69fa45b)
 
-- aliases DSL on Base for shorthand method names (377632f)
-- lookup_order DSL on Blueprint for ancestor traversal (377632f)
-- find_or_create pattern on Blueprint (377632f)
-- Tests for inherited registries, parent-scoped find, collection_find_by kwargs, find_or_create, ascending_find, and parent_present? (2d92945)
+## [0.1.3] - 2026-03-13
 
-### Changed
+### Added
 
-- Collections initialize before blueprints (377632f)
-- Fix find parent scoping and collection_find_by kwargs handling (3ebfc3e)
+- ancestor DSL and ancestors_for for path-based hierarchy building (7027e06)

data/README.md

@@ -224,6 +224,51 @@ When two presets share identical structure or one is structurally contained with
 
 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.
 
+## Factory Usage Recording
+
+If you're migrating an existing test suite to Foundries, the recording feature can help you discover which factory call patterns appear most often — and would make good preset candidates.
+
+Add to your `spec_helper.rb`:
+
+```ruby
+require "foundries/recording"
+```
+
+Then run your suite with the environment variable:
+
+```
+FOUNDRIES_RECORD=1 bundle exec rspec
+```
+
+After the suite finishes, a summary is printed to stdout:
+
+```
+[Foundries] Recording complete. 482 tests, 3841 factory creates.
+[Foundries] Top preset candidates:
+  1. team > [project > [task], user] (34 tests, score: 102)
+  2. team > [user] (28 tests, score: 56)
+  3. team > [project > [task > [comment]], user] (12 tests, score: 60)
+[Foundries] Full report: tmp/foundries/recording.json
+```
+
+The full JSON report at `tmp/foundries/recording.json` includes per-test breakdowns and all candidates with the test names that use each pattern.
+
+### Parallel tests
+
+Recording works with [parallel_tests](https://github.com/grosser/parallel_tests). Each worker writes its own file, then a rake task merges the results:
+
+```
+FOUNDRIES_RECORD=1 bundle exec parallel_rspec
+rake foundries:recording:merge
+```
+
+To use the rake task, add to your `Rakefile`:
+
+```ruby
+require "foundries/recording/rake_task"
+Foundries::Recording::RakeTask.install
+```
+
 ## Requirements
 
 - Ruby >= 4.0

data/lib/foundries/recording/aggregator.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative "node"
+
+module Foundries
+  module Recording
+    class Aggregator
+      def initialize(results)
+        @results = results
+      end
+
+      def candidates
+        return [] if @results.empty?
+
+        normalized = normalize_results
+        full_tree_candidates = group_by_full_tree(normalized)
+        subtree_candidates = find_common_subtrees(normalized)
+        merged = merge_candidates(full_tree_candidates, subtree_candidates)
+        filtered = merged.reject { |c| c[:tree_size] <= 1 }
+        filtered.sort_by { |c| -c[:score] }
+      end
+
+      private
+
+      def normalize_results
+        @results.transform_values(&:normalize)
+      end
+
+      def group_by_full_tree(normalized)
+        groups = Hash.new { |h, k| h[k] = [] }
+
+        normalized.each do |test_id, root|
+          structure = root_structure(root)
+          groups[structure] << test_id
+        end
+
+        groups.map do |structure, tests|
+          sample_root = normalized[tests.first]
+          tree_size = sample_root.children.sum(&:tree_size)
+          {
+            structure: structure,
+            frequency: tests.size,
+            tree_size: tree_size,
+            score: tests.size * tree_size,
+            tests: tests.map(&:to_s)
+          }
+        end
+      end
+
+      def root_structure(root)
+        root.children.sort_by(&:signature).map(&:signature).join(", ")
+      end
+
+      def find_common_subtrees(normalized)
+        subtree_tests = Hash.new { |h, k| h[k] = Set.new }
+        subtree_nodes = {}
+
+        normalized.each do |test_id, root|
+          root.children.each do |child|
+            extract_nontrivial_subtrees(child).each do |subtree|
+              sig = subtree.signature
+              subtree_tests[sig] << test_id
+              subtree_nodes[sig] ||= subtree
+            end
+          end
+        end
+
+        subtree_tests.map do |sig, tests|
+          subtree = subtree_nodes[sig]
+          {
+            structure: sig,
+            frequency: tests.size,
+            tree_size: subtree.tree_size,
+            score: tests.size * subtree.tree_size,
+            tests: tests.map(&:to_s)
+          }
+        end
+      end
+
+      def extract_nontrivial_subtrees(node)
+        subtrees = []
+        # A non-trivial subtree is a node that has children
+        subtrees << node unless node.children.empty?
+        node.children.each do |child|
+          subtrees.concat(extract_nontrivial_subtrees(child))
+        end
+        subtrees
+      end
+
+      def merge_candidates(full_tree, subtree)
+        by_structure = {}
+
+        full_tree.each do |candidate|
+          by_structure[candidate[:structure]] = candidate
+        end
+
+        subtree.each do |candidate|
+          if by_structure.key?(candidate[:structure])
+            existing = by_structure[candidate[:structure]]
+            merged_tests = (existing[:tests] + candidate[:tests]).uniq
+            frequency = merged_tests.size
+            tree_size = candidate[:tree_size]
+            by_structure[candidate[:structure]] = {
+              structure: candidate[:structure],
+              frequency: frequency,
+              tree_size: tree_size,
+              score: frequency * tree_size,
+              tests: merged_tests
+            }
+          else
+            by_structure[candidate[:structure]] = candidate
+          end
+        end
+
+        by_structure.values
+      end
+    end
+  end
+end

data/lib/foundries/recording/collector.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+require_relative "node"
+
+module Foundries
+  module Recording
+    class Collector
+      def initialize
+        @results = {}
+        @total_creates = 0
+        @subscriber = nil
+        @stack = nil
+        @current_root = nil
+      end
+
+      def start_test(test_id)
+        @current_root = MutableNode.new(:__root__, [])
+        @stack = [@current_root]
+
+        @subscriber = ActiveSupport::Notifications.subscribe(
+          "factory_bot.run_factory",
+          Subscriber.new(self)
+        )
+      end
+
+      def stop_test(test_id)
+        ActiveSupport::Notifications.unsubscribe(@subscriber)
+        @subscriber = nil
+
+        @results[test_id] = freeze_tree(@current_root)
+        @stack = nil
+        @current_root = nil
+      end
+
+      attr_reader :results
+
+      attr_reader :total_creates
+
+      # @api private — called by the Subscriber
+      def handle_start(payload)
+        return unless payload[:strategy] == :create
+
+        traits = payload[:traits] || []
+        mutable = MutableNode.new(payload[:name], traits)
+        @stack.last.children << mutable
+        @stack.push(mutable)
+      end
+
+      # @api private — called by the Subscriber
+      def handle_finish(payload)
+        return unless payload[:strategy] == :create
+
+        @stack.pop
+        @total_creates += 1
+      end
+
+      private
+
+      def freeze_tree(mutable)
+        frozen_children = mutable.children.map { |child| freeze_tree(child) }
+        Node.new(
+          factory: mutable.factory,
+          traits: mutable.traits,
+          children: frozen_children
+        )
+      end
+
+      MutableNode = Struct.new(:factory, :traits) do
+        def children
+          @children ||= []
+        end
+      end
+
+      class Subscriber
+        def initialize(collector)
+          @collector = collector
+        end
+
+        def start(_name, _id, payload)
+          @collector.handle_start(payload)
+        end
+
+        def finish(_name, _id, payload)
+          @collector.handle_finish(payload)
+        end
+      end
+    end
+  end
+end

data/lib/foundries/recording/node.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Foundries
+  module Recording
+    class Node
+      attr_reader :factory, :traits, :children
+
+      def initialize(factory:, traits: [], children: [])
+        @factory = factory.to_sym
+        @traits = traits.map(&:to_sym).sort.freeze
+        @children = children.freeze
+        @self_signature = compute_self_signature
+        @signature = compute_signature
+        @tree_size = 1 + children.sum(&:tree_size)
+        freeze
+      end
+
+      attr_reader :signature, :self_signature, :tree_size
+
+      def normalize
+        normalized_children = children.map(&:normalize)
+        deduped = normalized_children
+          .group_by(&:self_signature)
+          .map { |_sig, group| group.max_by(&:tree_size) }
+          .sort_by(&:signature)
+        self.class.new(factory: factory, traits: traits, children: deduped)
+      end
+
+      def to_h
+        {
+          factory: factory.to_s,
+          traits: traits.map(&:to_s),
+          children: children.map(&:to_h)
+        }
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && signature == other.signature
+      end
+
+      alias_method :eql?, :==
+
+      def hash
+        signature.hash
+      end
+
+      def to_s
+        signature
+      end
+
+      private
+
+      def compute_self_signature
+        base = factory.to_s
+        base = "#{base}[#{traits.map { |t| ":#{t}" }.join(", ")}]" unless traits.empty?
+        base
+      end
+
+      def compute_signature
+        base = @self_signature
+        unless children.empty?
+          sorted_children = children.sort_by(&:signature)
+          base = "#{base} > [#{sorted_children.map(&:signature).join(", ")}]"
+        end
+        base
+      end
+    end
+  end
+end

data/lib/foundries/recording/rake_task.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "rake"
+require_relative "../recording"
+
+module Foundries
+  module Recording
+    class RakeTask
+      include Rake::DSL
+
+      def self.install(output_path: Recording::DEFAULT_OUTPUT_PATH)
+        new.install_tasks(output_path: output_path)
+      end
+
+      def install_tasks(output_path:)
+        namespace :foundries do
+          namespace :recording do
+            desc "Merge per-worker recording files into a single report"
+            task :merge do
+              dir = File.dirname(output_path)
+              base = File.basename(output_path, File.extname(output_path))
+              ext = File.extname(output_path)
+              pattern = File.join(dir, "#{base}-*#{ext}")
+              files = Dir.glob(pattern).sort
+
+              if files.empty?
+                $stdout.puts "[Foundries] No worker recording files found matching #{pattern}"
+                next
+              end
+
+              Foundries::Recording::RakeTask.merge(files, output_path: output_path)
+            end
+          end
+        end
+      end
+
+      def self.merge(files, output_path:)
+        summary = Reporter.merge_files(files, output_path: output_path)
+        $stdout.puts summary
+      end
+    end
+  end
+end

data/lib/foundries/recording/reporter.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "fileutils"
+require_relative "aggregator"
+require_relative "node"
+
+module Foundries
+  module Recording
+    class Reporter
+      MAX_STDOUT_CANDIDATES = 10
+
+      def self.merge_files(paths, output_path:)
+        combined_per_test = {}
+        total_creates = 0
+
+        paths.each do |path|
+          data = JSON.parse(File.read(path))
+          total_creates += data["total_factory_creates"]
+          data["per_test"].each do |test_id, test_data|
+            combined_per_test[test_id] = test_data
+          end
+        end
+
+        total_tests = combined_per_test.size
+
+        results = combined_per_test.transform_values do |test_data|
+          children = (test_data["tree"] || []).map { |h| node_from_hash(h) }
+          Node.new(factory: :__root__, children: children)
+        end
+
+        reporter = new(results: results, total_creates: total_creates, total_tests: total_tests)
+        reporter.write_json(output_path)
+        reporter.summary(json_path: output_path)
+      end
+
+      def self.node_from_hash(hash)
+        children = (hash["children"] || []).map { |c| node_from_hash(c) }
+        Node.new(
+          factory: hash["factory"].to_sym,
+          traits: (hash["traits"] || []).map(&:to_sym),
+          children: children
+        )
+      end
+
+      private_class_method :node_from_hash
+
+      def initialize(results:, total_creates:, total_tests:)
+        @results = results
+        @total_creates = total_creates
+        @total_tests = total_tests
+      end
+
+      def candidates
+        @candidates ||= Aggregator.new(@results).candidates
+      end
+
+      def write_json(path)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, JSON.pretty_generate(json_data))
+      end
+
+      def summary(json_path: nil)
+        lines = []
+        lines << "[Foundries] Recording complete. #{@total_tests} tests, #{@total_creates} factory creates."
+
+        if candidates.empty?
+          lines << "[Foundries] No preset candidates found."
+        else
+          lines << "[Foundries] Top preset candidates:"
+          candidates.first(MAX_STDOUT_CANDIDATES).each_with_index do |candidate, index|
+            lines << "  #{index + 1}. #{candidate[:structure]} (#{candidate[:frequency]} tests, score: #{candidate[:score]})"
+          end
+        end
+
+        lines << "[Foundries] Full report: #{json_path}" if json_path
+
+        lines.join("\n")
+      end
+
+      private
+
+      def json_data
+        {
+          recorded_at: Time.now.utc.iso8601,
+          total_tests: @total_tests,
+          total_factory_creates: @total_creates,
+          candidates: candidates.map { |c| stringify_candidate(c) },
+          per_test: build_per_test
+        }
+      end
+
+      def stringify_candidate(candidate)
+        {
+          structure: candidate[:structure],
+          frequency: candidate[:frequency],
+          tree_size: candidate[:tree_size],
+          score: candidate[:score],
+          tests: candidate[:tests]
+        }
+      end
+
+      def build_per_test
+        @results.each_with_object({}) do |(test_id, root), hash|
+          hash[test_id.to_s] = {
+            factories_created: root.children.size,
+            tree: root.children.map(&:to_h)
+          }
+        end
+      end
+    end
+  end
+end

data/lib/foundries/recording.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "recording/collector"
+require_relative "recording/reporter"
+
+module Foundries
+  module Recording
+    DEFAULT_OUTPUT_PATH = "tmp/foundries/recording.json"
+
+    class << self
+      attr_writer :enabled, :output_path
+
+      def enabled?
+        return @enabled unless @enabled.nil?
+        ENV["FOUNDRIES_RECORD"] == "1"
+      end
+
+      def collector
+        @collector ||= Collector.new
+      end
+
+      def output_path
+        @output_path || DEFAULT_OUTPUT_PATH
+      end
+
+      def worker_output_path
+        worker_id = ENV["TEST_ENV_NUMBER"]
+        return output_path if worker_id.nil?
+
+        suffix = worker_id.empty? ? Process.pid.to_s : worker_id
+        base = output_path
+        ext = File.extname(base)
+        "#{base.chomp(ext)}-#{suffix}#{ext}"
+      end
+
+      def reset!
+        @collector = nil
+        @enabled = nil
+        @output_path = nil
+      end
+
+      def report!
+        total_tests = collector.results.size
+        reporter = Reporter.new(
+          results: collector.results,
+          total_creates: collector.total_creates,
+          total_tests: total_tests
+        )
+        path = worker_output_path
+        reporter.write_json(path)
+        $stdout.puts reporter.summary(json_path: path)
+      end
+    end
+  end
+end
+
+if Foundries::Recording.enabled? && defined?(RSpec)
+  RSpec.configure do |config|
+    config.before(:each) do |example|
+      Foundries::Recording.collector.start_test(example.full_description)
+    end
+
+    config.after(:each) do |example|
+      Foundries::Recording.collector.stop_test(example.full_description)
+    end
+
+    config.after(:suite) do
+      Foundries::Recording.report!
+    end
+  end
+end

data/lib/foundries/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Foundries
-  VERSION = "0.1.3"
-  RELEASE_DATE = "2026-03-13"
+  VERSION = "0.1.4"
+  RELEASE_DATE = "2026-03-16"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: foundries
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - John Dowd
@@ -54,6 +54,12 @@ files:
 - lib/foundries.rb
 - lib/foundries/base.rb
 - lib/foundries/blueprint.rb
+- lib/foundries/recording.rb
+- lib/foundries/recording/aggregator.rb
+- lib/foundries/recording/collector.rb
+- lib/foundries/recording/node.rb
+- lib/foundries/recording/rake_task.rb
+- lib/foundries/recording/reporter.rb
 - lib/foundries/similarity.rb
 - lib/foundries/similarity/comparator.rb
 - lib/foundries/similarity/recorder.rb