foundries 0.1.0

data/lib/foundries/blueprint.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+module Foundries
+  # Blueprint is the base class for individual factory wrappers within a Foundry.
+  #
+  # Each Blueprint wraps one or more factory_bot factories and knows how to:
+  # - Create records using factory_bot
+  # - Track created records in a collection
+  # - Navigate parent-child relationships
+  # - Find existing records before creating duplicates
+  #
+  # Subclass Blueprint and use the class-level DSL to declare behavior:
+  #
+  #   class UserBlueprint < Foundries::Blueprint
+  #     handles :user, :admin
+  #     factory :user
+  #     collection :users
+  #     parent :none
+  #     permitted_attrs %i[name email]
+  #   end
+  #
+  class Blueprint
+    include FactoryBot::Syntax::Methods
+
+    attr_reader :foundry
+
+    class << self
+      def handles(*methods)
+        @handled_methods ||= []
+        @handled_methods.concat(methods)
+      end
+
+      def handled_methods
+        @handled_methods || []
+      end
+
+      # Declare which factory_bot factory this blueprint uses.
+      # If not set, inferred from the class name.
+      def factory(name = nil)
+        if name
+          @factory_name = name
+        else
+          @factory_name || inferred_factory_name
+        end
+      end
+
+      def factory_name
+        factory
+      end
+
+      # Declare the collection name for tracking created records.
+      # This also defines `#collection` and `#record_class` instance methods.
+      def collection(method_name = nil)
+        return @collection_name unless method_name
+
+        @collection_name = method_name
+
+        define_method(:collection) do
+          foundry.send(:"#{method_name}_collection")
+        end
+
+        define_method(:record_class) do
+          method_name.to_s.classify.constantize
+        end
+      end
+
+      attr_reader :collection_name
+
+      # Declare the foreign key used to link to the parent.
+      def parent_key(key = nil)
+        return @parent_key_name unless key
+
+        @parent_key_name = key
+        define_method(:parent_key) { key }
+      end
+
+      # Declare how to find the parent record from `current` state.
+      #
+      #   parent :none        - no parent relationship
+      #   parent :self        - self-referential (e.g. nested categories)
+      #   parent :competency  - reads current.competency
+      #
+      def parent(method_name = nil)
+        return @parent_method unless method_name
+
+        @parent_method = method_name
+
+        if method_name == :none
+          define_method(:same_parent?) { |_| true }
+        elsif method_name == :self
+          define_method(:same_parent?) { |_| true }
+          define_method(:parent) do
+            current.send(current_accessor)
+          end
+        else
+          define_method(:parent) do
+            current.send(method_name)
+          end
+
+          define_singleton_method(:parent_accessor) do
+            method_name
+          end
+        end
+      end
+
+      # Declare which attributes are allowed through to factory_bot.
+      def permitted_attrs(attr_list)
+        define_method(:permitted_attrs) do |attrs|
+          keys = attr_list.dup
+          keys << parent_key if parent_key
+          attrs.slice(*keys)
+        end
+      end
+
+      # Declare nested attributes (for accepts_nested_attributes_for).
+      def nested_attrs(hash)
+        nested_object_name, attr_names = hash.shift
+
+        define_method(:nested_attrs) do |attrs|
+          attrs_to_nest = attrs.slice(*attr_names)
+          key = :"#{nested_object_name}_attributes"
+          {key => attrs_to_nest}
+        end
+      end
+
+      # Load state from an existing object back into a foundry.
+      def load_state_from(object, foundry)
+        return unless respond_to?(:parent_accessor)
+
+        parent_object = object.send(parent_accessor)
+        foundry.load_existing_objects(parent_object)
+      end
+
+      private
+
+      def inferred_factory_name
+        name&.demodulize&.delete_suffix("Blueprint")&.underscore&.to_sym
+      end
+    end
+
+    def self.new(...)
+      instance = super
+      foundry = instance.foundry
+      recorder = foundry&.instance_variable_get(:@_similarity_recorder)
+      instance._wrap_for_similarity_recording!(recorder) if recorder
+      instance
+    end
+
+    def initialize(foundry)
+      @foundry = foundry
+      @attrs = {}
+    end
+
+    def _wrap_for_similarity_recording!(recorder)
+      methods_to_wrap = self.class.public_instance_methods(false).select do |m|
+        self.class.instance_method(m).parameters.any? { |type, _| type == :block }
+      end
+
+      methods_to_wrap.each do |method_name|
+        original = method(method_name)
+        define_singleton_method(method_name) do |*args, **kwargs, &block|
+          recorder.record(method_name.to_s, has_block: !block.nil?) do
+            original.call(*args, **kwargs, &block)
+          end
+        end
+      end
+    end
+
+    delegate :current=, :current, :update_current, :execute_and_restore_state,
+      to: :foundry
+
+    def assume_trait?(val)
+      val.is_a?(Symbol) || val.is_a?(Array)
+    end
+
+    def inspect
+      self.class.name
+    end
+
+    def parent_key
+      nil
+    end
+
+    def parent
+      nil
+    end
+
+    # Saves current state, yields, then restores state.
+    # Use this when entering a nested block to scope context.
+    def update_state_for_block(object, &block)
+      execute_and_restore_state do
+        update_current(object)
+        current.resource = object
+        instance_exec(&block)
+      end
+    end
+
+    # Find a record in the collection by name, falling back to the database.
+    def find(name, col_name: "name")
+      raise "#find called with nil :name, for col_name: #{col_name}." unless name
+
+      found_record = collection.detect do |object|
+        object.send(col_name).casecmp?(name) && same_parent?(object)
+      end
+
+      found_record ||
+        record_class.find_by(col_name => name)&.tap { |rec| collection << rec }
+    end
+
+    # Find a record in the collection by arbitrary criteria, falling back to the database.
+    def find_by(criteria = {})
+      found_record = collection.detect do |object|
+        criteria.all? { |attr, value| object.send(attr) == value }
+      end
+
+      return found_record if found_record
+
+      record_class.find_by(criteria)&.tap { |record| collection << record }
+    end
+
+    def same_parent?(object)
+      return true unless parent
+
+      object.send(parent_key) == parent_id
+    end
+
+    def parent_id
+      parent&.id
+    end
+
+    def current_accessor
+      self.class.name.demodulize.underscore.delete_suffix("_blueprint")
+    end
+
+    def find_or_create_object
+      send(:"#{mode}_object")
+    end
+
+    def mode
+      current.resource.nil? ? :find : :create
+    end
+
+    def reset_attrs_and_type
+      @type = nil
+      reset_attrs
+    end
+
+    def reset_attrs
+      @attrs = {}
+    end
+
+    # Delegate unknown methods to the foundry so that all blueprint methods
+    # are available in nested blocks. Also supports dynamic find_<klass>_by.
+    def method_missing(name, *args, **kwargs, &block)
+      if (match = missing_find_by_request?(name))
+        klass_name = match.named_captures["klass"]
+        return collection_find_by(klass_name, args)
+      end
+
+      if foundry.respond_to?(name)
+        return foundry.send(name, *args, **kwargs, &block)
+      end
+
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      missing_find_by_request?(name) || foundry.respond_to?(name) || super
+    end
+
+    private
+
+    def missing_find_by_request?(method_name)
+      method_name.match(/^find_(?<klass>.*)_by$/)
+    end
+
+    def collection_find_by(klass_name, args)
+      attrs = args.first
+      target_collection_name = "#{klass_name.pluralize}_collection"
+      objects = foundry.send(target_collection_name)
+      objects.detect do |object|
+        attrs.all? { |(attr, value)| object.send(attr) == value }
+      end
+    end
+  end
+end

data/lib/foundries/similarity/comparator.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Foundries
+  module Similarity
+    module Comparator
+      def self.compare(new_key, new_tree, registry)
+        warnings = []
+
+        registry.each do |existing_key, existing_tree|
+          next if existing_key == new_key
+          pair_key = [new_key, existing_key].sort
+
+          if new_tree == existing_tree
+            warnings << {
+              pair: pair_key,
+              message: "[Foundries] Preset :#{preset_name(new_key)} and " \
+                ":#{preset_name(existing_key)} have identical structure " \
+                "(#{display_tree(new_tree)})"
+            }
+          elsif existing_tree.contains?(new_tree)
+            warnings << {
+              pair: pair_key,
+              message: "[Foundries] Preset :#{preset_name(new_key)} is " \
+                "structurally contained within :#{preset_name(existing_key)}"
+            }
+          elsif new_tree.contains?(existing_tree)
+            warnings << {
+              pair: pair_key,
+              message: "[Foundries] Preset :#{preset_name(existing_key)} is " \
+                "structurally contained within :#{preset_name(new_key)}"
+            }
+          end
+        end
+
+        warnings
+      end
+
+      def self.preset_name(key)
+        key.to_s.split(".").last
+      end
+
+      def self.display_tree(tree)
+        tree.children.map(&:to_s).join(", ")
+      end
+
+      private_class_method :preset_name, :display_tree
+    end
+  end
+end

data/lib/foundries/similarity/recorder.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "structure_tree"
+
+module Foundries
+  module Similarity
+    class Recorder
+      def initialize
+        @root = StructureTree.root(children: [])
+        @stack = [@root]
+      end
+
+      def record(method_name, has_block:)
+        node = StructureTree.new(method_name)
+        current_parent.children << node
+        if has_block
+          @stack.push(node)
+          yield
+          @stack.pop
+        elsif block_given?
+          yield
+        end
+      end
+
+      def normalized_tree
+        @root.normalize
+      end
+
+      private
+
+      def current_parent
+        @stack.last
+      end
+    end
+  end
+end

data/lib/foundries/similarity/structure_tree.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Foundries
+  module Similarity
+    class StructureTree
+      attr_reader :name, :children
+
+      def initialize(name, children: [])
+        @name = name.to_s
+        @children = children
+      end
+
+      def self.root(children:)
+        new("__root__", children: children)
+      end
+
+      def normalize
+        normalized_children = children.map(&:normalize)
+        collapsed = normalized_children.flat_map { |child| child.collapse_into(name) }
+        deduped = collapsed
+          .group_by(&:name)
+          .map { |_name, group| group.max_by(&:descendant_count) }
+          .sort_by(&:name)
+        self.class.new(name, children: deduped)
+      end
+
+      def collapse_into(parent_name)
+        if name == parent_name && !children.empty?
+          children
+        else
+          [self]
+        end
+      end
+
+      def descendant_count
+        children.sum { |c| 1 + c.descendant_count }
+      end
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          name == other.name &&
+          children == other.children
+      end
+
+      alias_method :eql?, :==
+
+      def hash
+        [name, children].hash
+      end
+
+      def contains?(other)
+        return true if self == other
+
+        embeds?(other) || children.any? { |child| child.contains?(other) }
+      end
+
+      def embeds?(other)
+        return false unless name == other.name
+
+        other.children.all? do |other_child|
+          children.any? { |child| child.embeds?(other_child) }
+        end
+      end
+
+      def to_s
+        if children.empty?
+          name
+        else
+          "#{name} > [#{children.map(&:to_s).join(", ")}]"
+        end
+      end
+    end
+  end
+end

data/lib/foundries/similarity.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "similarity/structure_tree"
+require_relative "similarity/recorder"
+require_relative "similarity/comparator"
+
+module Foundries
+  module Similarity
+    class << self
+      attr_writer :enabled
+
+      def enabled?
+        return @enabled unless @enabled.nil?
+        ENV["FOUNDRIES_SIMILARITY"] == "1"
+      end
+
+      def registry
+        @registry ||= {}
+      end
+
+      def warned_pairs
+        @warned_pairs ||= Set.new
+      end
+
+      def reset!
+        @registry = {}
+        @warned_pairs = Set.new
+        @enabled = nil
+      end
+    end
+  end
+end

data/lib/foundries/snapshot/adapter.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Foundries
+  module Snapshot
+    module Adapter
+      def self.for(connection)
+        case connection.adapter_name
+        when /postgresql/i
+          Adapters::PostgresAdapter.new(connection)
+        when /sqlite/i
+          Adapters::SqliteAdapter.new(connection)
+        else
+          raise "Unsupported adapter: #{connection.adapter_name}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Foundries
+  module Snapshot
+    module Adapters
+      class PostgresAdapter
+        def initialize(connection)
+          @connection = connection
+        end
+
+        def table_names
+          @connection.tables - %w[schema_migrations ar_internal_metadata]
+        end
+
+        def empty?(table_name)
+          @connection.select_value("SELECT NOT EXISTS (SELECT 1 FROM #{quoted(table_name)})")
+        end
+
+        def capture(table_name, io)
+          raw = @connection.raw_connection
+          raw.copy_data("COPY #{quoted(table_name)} TO STDOUT") do
+            while (row = raw.get_copy_data)
+              io.write(row)
+            end
+          end
+        end
+
+        def restore(table_name, io)
+          raw = @connection.raw_connection
+          raw.copy_data("COPY #{quoted(table_name)} FROM STDIN") do
+            io.each_line do |line|
+              raw.put_copy_data(line)
+            end
+          end
+        end
+
+        def disable_referential_integrity
+          @connection.execute("SET session_replication_role = replica")
+          yield
+        ensure
+          @connection.execute("SET session_replication_role = DEFAULT")
+        end
+
+        def reset_sequence(table_name)
+          pk = @connection.primary_key(table_name)
+          return unless pk
+
+          # Check for sequence first — UUID PKs have no sequence
+          seq = @connection.select_value(
+            "SELECT pg_get_serial_sequence(#{@connection.quote(table_name)}, #{@connection.quote(pk)})"
+          )
+          return unless seq
+
+          max_id = @connection.select_value(
+            "SELECT COALESCE(MAX(#{@connection.quote_column_name(pk)}), 0) FROM #{quoted(table_name)}"
+          )
+          @connection.execute("SELECT setval(#{@connection.quote(seq)}, #{max_id})")
+        end
+
+        private
+
+        def quoted(table_name)
+          @connection.quote_table_name(table_name)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Foundries
+  module Snapshot
+    module Adapters
+      class SqliteAdapter
+        def initialize(connection)
+          @connection = connection
+        end
+
+        def table_names
+          @connection.tables - %w[schema_migrations ar_internal_metadata]
+        end
+
+        def empty?(table_name)
+          @connection.select_value("SELECT COUNT(*) FROM #{quoted(table_name)}") == 0
+        end
+
+        def capture(table_name, io)
+          rows = @connection.select_all("SELECT * FROM #{quoted(table_name)}")
+          rows.each do |row|
+            values = row.values.map { |v| @connection.quote(v) }.join(", ")
+            columns = row.keys.map { |k| @connection.quote_column_name(k) }.join(", ")
+            io.puts "INSERT INTO #{quoted(table_name)} (#{columns}) VALUES (#{values});"
+          end
+        end
+
+        def restore(table_name, io)
+          io.each_line do |line|
+            @connection.execute(line.strip) unless line.strip.empty?
+          end
+        end
+
+        def disable_referential_integrity
+          @connection.execute("PRAGMA defer_foreign_keys = ON")
+          yield
+        ensure
+          @connection.execute("PRAGMA defer_foreign_keys = OFF")
+        end
+
+        def reset_sequence(table_name)
+          # SQLite auto-increments handle this naturally
+        end
+
+        private
+
+        def quoted(table_name)
+          @connection.quote_table_name(table_name)
+        end
+      end
+    end
+  end
+end

data/lib/foundries/snapshot/fingerprint.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Foundries
+  module Snapshot
+    class Fingerprint
+      def initialize(connection, source_paths: [])
+        @connection = connection
+        @source_paths = Array(source_paths)
+      end
+
+      def current
+        digest = Digest::MD5.new
+        digest.update(schema_version)
+        @source_paths.sort.each do |path|
+          digest.update(File.read(path)) if File.exist?(path)
+        end
+        digest.hexdigest
+      end
+
+      private
+
+      def schema_version
+        @connection.select_value(
+          "SELECT MAX(version) FROM schema_migrations"
+        ).to_s
+      end
+    end
+  end
+end