foundries 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8245b09fe2227ef4a25d5751c30f4a94a1d2d80519ef5fb97b8ba2b9dc527ef
-  data.tar.gz: 24162154115e9f413117fb88d71aa0cbc19374cbbf9b6fa059f23e36535511e5
+  metadata.gz: 05ac2ed1c8c00feab7b078f4e3dcd9b5fd8c24fdb6c1f7278aab3c4df6f85898
+  data.tar.gz: 174371e6e22eb9b6764dd4d70fb90988bc276e4a0e32c032b45254d924261f80
 SHA512:
-  metadata.gz: f0b22d20d6edc795ef1c7a2f3403b1a7e5cbbbc0d3ca4bd19fc82c25992bcea6d460175df202d8cd0465dd328a8bc189672171423ed283aa7879390450261318
-  data.tar.gz: 1ece80e18cdc964013db346ec665e2919f146bda411ddaf4254abb4c714c712a4a692cb30241a051da98029c164fbbc77b1e4fc44c2dac0cadda396c0fbccadf
+  metadata.gz: f79398b03c229960553bb6d2283254f5fa832166e497811ba7fc488db50a499288ee987a379f18e92cdc3a237bae6dcc41aefb5c6ddb1f3ecc861b7f354b62cb
+  data.tar.gz: 8870ca65270252f4f7f29392e456a230c167aa170a7d6bacc54d6a10452e3398a42fefc3767d283faac944e0620c800d9c58dd1170bbeff4f932fdf282fcc48e

data/CHANGELOG.md

@@ -5,22 +5,25 @@ 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.5] - 2026-08-12
 
-### Added
+### Changed
+
+- Development dependencies are locked (1129826)
+
+### Fixed
 
-- ancestor DSL and ancestors_for for path-based hierarchy building (7027e06)
+- Snapshot no longer caches a partial tree when a preset writes to a table that already held rows (2e9f863)
+- Lint under standard 1.56.0 (52be9eb)
+- Releases write a SHA512 checksum again (813a2ae)
 
-## [0.1.2] - 2026-03-12
+## [0.1.4] - 2026-03-16
 
 ### Added
 
-- 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)
+- 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)
 
 ### Changed
 
-- Collections initialize before blueprints (377632f)
-- Fix find parent scoping and collection_find_by kwargs handling (3ebfc3e)
+- README now covers Recording feature and parallel_tests support (69fa45b)

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/similarity/comparator.rb

@@ -28,7 +28,7 @@ module Foundries
       end
 
       def self.display_tree(tree)
-        tree.children.map(&:to_s).join(", ")
+        tree.children.join(", ")
       end
 
       private_class_method :preset_name, :display_tree

data/lib/foundries/similarity/structure_tree.rb

@@ -66,7 +66,7 @@ module Foundries
         if children.empty?
           name
         else
-          "#{name} > [#{children.map(&:to_s).join(", ")}]"
+          "#{name} > [#{children.join(", ")}]"
         end
       end
     end

data/lib/foundries/snapshot/adapters/postgres_adapter.rb

@@ -16,6 +16,10 @@ module Foundries
           @connection.select_value("SELECT NOT EXISTS (SELECT 1 FROM #{quoted(table_name)})")
         end
 
+        def count(table_name)
+          @connection.select_value("SELECT COUNT(*) FROM #{quoted(table_name)}")
+        end
+
         def capture(table_name, io)
           raw = @connection.raw_connection
           raw.copy_data("COPY #{quoted(table_name)} TO STDOUT") do

data/lib/foundries/snapshot/adapters/sqlite_adapter.rb

@@ -13,7 +13,11 @@ module Foundries
         end
 
         def empty?(table_name)
-          @connection.select_value("SELECT COUNT(*) FROM #{quoted(table_name)}") == 0
+          count(table_name) == 0
+        end
+
+        def count(table_name)
+          @connection.select_value("SELECT COUNT(*) FROM #{quoted(table_name)}")
         end
 
         def capture(table_name, io)

data/lib/foundries/snapshot/store.rb

@@ -25,11 +25,34 @@ module Foundries
 
       # Record which tables are empty before the preset block runs.
       # Only these tables will be captured after the block completes.
+      #
+      # The already-populated tables are counted too, so #capture can tell
+      # whether the preset wrote into one of them. A preset that only updates
+      # existing rows leaves the count unchanged and slips past this check;
+      # presets insert, so the count is a good enough signal.
       def record_empty_tables
-        @capturable_tables = @adapter.table_names.select { |t| @adapter.empty?(t) }
+        @capturable_tables = []
+        @preexisting_counts = {}
+
+        @adapter.table_names.each do |table|
+          if @adapter.empty?(table)
+            @capturable_tables << table
+          else
+            @preexisting_counts[table] = @adapter.count(table)
+          end
+        end
       end
 
       def capture
+        spoiled = spoiled_tables
+        unless spoiled.empty?
+          warn "[Foundries] Not caching preset :#{@preset_name} — it wrote to " \
+            "#{spoiled.join(", ")}, which already held rows when it ran. " \
+            "Only tables the preset fills from empty can be snapshotted, so " \
+            "caching this would restore an incomplete tree."
+          return
+        end
+
         tables = @capturable_tables || @adapter.table_names
 
         tmp_dir = Pathname.new("#{cache_dir}.#{$$}.tmp")
@@ -64,6 +87,17 @@ module Foundries
 
       private
 
+      # Pre-populated tables whose row count moved while the preset ran. Their
+      # new rows can't be told apart from the ones that were already there, so
+      # the snapshot would silently omit them.
+      def spoiled_tables
+        return [] unless @preexisting_counts
+
+        @preexisting_counts.filter_map do |table, count|
+          table unless @adapter.count(table) == count
+        end
+      end
+
       def cache_dir
         @cache_dir ||= Pathname.new(@storage_path).join(@preset_name)
       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.5"
+  RELEASE_DATE = "2026-08-12"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: foundries
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 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
@@ -87,7 +93,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Declarative trees of related data using factory_bot
 test_files: []