activecypher 0.5.0 → 0.6.0

data/lib/active_cypher/fixtures/parser.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Fixtures
+    # Parses a fixture profile file using instance_eval in a DSL context.
+    class Parser
+      attr_reader :file, :dsl_context
+
+      def initialize(file)
+        @file = file
+        @dsl_context = ActiveCypher::Fixtures::DSLContext.new
+      end
+
+      # Evaluates the profile file in the DSL context.
+      # Returns the DSLContext instance (which accumulates node/rel declarations).
+      def parse
+        code = File.read(file)
+        dsl_context.instance_eval(code, file)
+        dsl_context
+      end
+    end
+  end
+end

data/lib/active_cypher/fixtures/registry.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Fixtures
+    # Singleton registry for logical ref => model instance mapping
+    class Registry
+      @store = {}
+
+      class << self
+        # Store loaded instance
+        # @param ref [Symbol, String]
+        # @param obj [Object]
+        def add(ref, obj)
+          raise ArgumentError, "Duplicate fixture ref: #{ref.inspect}" if @store.key?(ref.to_sym)
+
+          @store[ref.to_sym] = obj
+        end
+
+        # Fetch in tests (`[]` delegate)
+        # @param ref [Symbol, String]
+        # @return [Object, nil]
+        def get(ref)
+          @store[ref.to_sym]
+        end
+
+        # Purge registry between loads
+        def reset!
+          @store.clear
+        end
+
+        # Allow bracket access: Registry[:foo]
+        def [](ref)
+          get(ref)
+        end
+
+        # For debugging or introspection
+        def all
+          @store.dup
+        end
+      end
+    end
+  end
+end

data/lib/active_cypher/fixtures/rel_builder.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Fixtures
+    class RelBuilder
+      # Builds a relationship between two nodes, enforcing cross-DB safety.
+      #
+      # @param _ref [Symbol, String] Logical reference for this relationship (not used for DB, but for registry/uniqueness)
+      # @param from_ref [Symbol, String] Logical ref of the start node
+      # @param type [Symbol, String] Relationship type (e.g., :LIKES)
+      # @param to_ref [Symbol, String] Logical ref of the end node
+      # @param props [Hash] Optional properties for the relationship
+      # @raise [ActiveCypher::FixtureError] if cross-DB relationship is attempted
+      # @return [void]
+      def build(_ref, from_ref, type, to_ref, props = {})
+        from = Registry.get(from_ref)
+        to   = Registry.get(to_ref)
+
+        raise FixtureError, "Missing from node: #{from_ref}" unless from
+        raise FixtureError, "Missing to node: #{to_ref}" unless to
+
+        from_conn = from.class.connection
+        to_conn   = to.class.connection
+
+        raise FixtureError, 'Cross-database relationship? Sorry, your data has commitment issues.' if from_conn != to_conn
+
+        from_label = from.class.labels.first
+        to_label   = to.class.labels.first
+
+        cypher = <<~CYPHER
+          MATCH (a:#{from_label} {name: $from_name}), (b:#{to_label} {name: $to_name})
+          CREATE (a)-[r:#{type} $props]->(b)
+          RETURN r
+        CYPHER
+
+        from_conn.execute_cypher(
+          cypher,
+          from_name: from.name,
+          to_name: to.name,
+          props: props
+        )
+
+        nil
+      end
+
+      # Bulk create relationships for performance using UNWIND batching
+      # @param rels [Array<Hash>] relationship definitions (from DSLContext)
+      # @param batch_size [Integer] batch size for UNWIND
+      def self.bulk_build(rels, batch_size: 200)
+        # Check all relationships for cross-DB violations first
+        rels.each do |rel|
+          from = Registry.get(rel[:from_ref])
+          to = Registry.get(rel[:to_ref])
+          raise FixtureError, "Both endpoints must exist: #{rel[:from_ref]}, #{rel[:to_ref]}" unless from && to
+
+          from_conn = from.class.connection
+          to_conn   = to.class.connection
+          raise FixtureError, 'Cross-database relationship? Sorry, your data has commitment issues.' if from_conn != to_conn
+        end
+
+        # Group by connection
+        grouped = rels.group_by do |rel|
+          from = Registry.get(rel[:from_ref])
+          from.class.connection
+        end
+
+        grouped.each do |conn, group|
+          group.each_slice(batch_size) do |batch|
+            unwind_batch = batch.map do |rel|
+              from = Registry.get(rel[:from_ref])
+              to   = Registry.get(rel[:to_ref])
+
+              {
+                from_name: from.name,
+                from_label: from.class.labels.first,
+                to_name: to.name,
+                to_label: to.class.labels.first,
+                props: rel[:props] || {},
+                type: rel[:type].to_s
+              }
+            end
+
+            cypher = <<~CYPHER
+              UNWIND $rows AS row
+              MATCH (a:#{unwind_batch.first[:from_label]} {name: row.from_name})
+              MATCH (b:#{unwind_batch.first[:to_label]} {name: row.to_name})
+              CREATE (a)-[r:#{unwind_batch.first[:type]} {props: row.props}]->(b)
+            CYPHER
+
+            conn.execute_cypher(cypher, rows: unwind_batch)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_cypher/fixtures.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Fixtures
+    # Something went wrong with your test fixtures.
+    # Maybe they're on vacation. Maybe they're just imaginary.
+    class FixtureError < StandardError; end
+
+    # You asked for a fixture that doesn't exist.
+    # It's playing hide and seek. Mostly hide.
+    class FixtureNotFoundError < StandardError; end
+
+    # Load a graph fixture profile.
+    # @param profile [Symbol, String, nil] the profile name (default: :default)
+    # @return [void]
+    def self.load(profile: nil)
+      # 1. Resolve file
+      profile_name = (profile || :default).to_s
+      fixtures_dir = File.expand_path('test/fixtures/graph', Dir.pwd)
+      file = File.join(fixtures_dir, "#{profile_name}.rb")
+      raise FixtureNotFoundError, "Fixture profile not found: #{profile_name} (#{file})" unless File.exist?(file)
+
+      # 2. Reset registry
+      Registry.reset!
+
+      # 3. Parse the profile file (to discover which models are referenced)
+      parser = Parser.new(file)
+      dsl_context = parser.parse
+
+      # 4. Validate relationships upfront (cross-DB)
+      validate_relationships(dsl_context.relationships)
+
+      # 5. Gather unique connections for all model classes referenced in this profile
+      model_classes = dsl_context.nodes.map { |node| node[:model_class] }.uniq
+      connections = model_classes.map do |klass|
+        klass.connection
+      rescue StandardError
+        nil
+      end.compact.uniq
+
+      # 6. Wipe all nodes in each relevant connection
+      connections.each do |conn|
+        conn.execute_cypher('MATCH (n) DETACH DELETE n')
+      rescue StandardError => e
+        warn "[ActiveCypher::Fixtures.load] Failed to clear connection #{conn.inspect}: #{e.class}: #{e.message}"
+      end
+
+      # 7. Evaluate nodes and relationships (batched if large)
+      if dsl_context.nodes.size > 100 || dsl_context.relationships.size > 200
+        NodeBuilder.bulk_build(dsl_context.nodes)
+        # Create all nodes first, then validate relationships again with populated Registry
+        validate_relationships(dsl_context.relationships)
+        RelBuilder.bulk_build(dsl_context.relationships)
+      else
+        dsl_context.nodes.each do |node|
+          NodeBuilder.build(node[:ref], node[:model_class], node[:props])
+        end
+        rel_builder = RelBuilder.new
+        dsl_context.relationships.each do |rel|
+          rel_builder.build(rel[:ref], rel[:from_ref], rel[:type], rel[:to_ref], rel[:props])
+        end
+      end
+
+      # 8. Return registry for convenience
+      Registry
+    end
+
+    # Clear all nodes in all known connections.
+    # @return [void]
+    def self.clear_all
+      # Find all concrete (non-abstract) model classes inheriting from ActiveCypher::Base
+      model_classes = []
+      ObjectSpace.each_object(Class) do |klass|
+        next unless klass < ActiveCypher::Base
+        next if klass.respond_to?(:abstract_class?) && klass.abstract_class?
+
+        model_classes << klass
+      end
+
+      # Gather unique connections from all model classes
+      connections = model_classes.map do |klass|
+        klass.connection
+      rescue StandardError
+        nil
+      end.compact.uniq
+
+      # Wipe all nodes in each connection
+      connections.each do |conn|
+        conn.execute_cypher('MATCH (n) DETACH DELETE n')
+      rescue StandardError => e
+        warn "[ActiveCypher::Fixtures.clear_all] Failed to clear connection #{conn.inspect}: #{e.class}: #{e.message}"
+      end
+      true
+    end
+
+    # Validates relationships for cross-DB issues
+    # @param relationships [Array<Hash>] array of relationship definitions
+    # @raise [FixtureError] if cross-DB relationship is found
+    def self.validate_relationships(relationships)
+      model_connections = {}
+
+      # First build a mapping of model class => connection details
+      ObjectSpace.each_object(Class) do |klass|
+        next unless klass < ActiveCypher::Base
+        next if klass.respond_to?(:abstract_class?) && klass.abstract_class?
+
+        begin
+          conn = klass.connection
+          # Store connection details for comparison
+          model_connections[klass] = {
+            adapter: conn.class.name,
+            config: conn.instance_variable_get(:@config),
+            object_id: conn.object_id
+          }
+        rescue StandardError
+          # Skip if can't get connection
+        end
+      end
+
+      relationships.each do |rel|
+        from_ref = rel[:from_ref]
+        to_ref = rel[:to_ref]
+
+        # Get node classes from DSL context
+        # In real data, nodes have already been created by this point
+        from_node = Registry.get(from_ref)
+        to_node = Registry.get(to_ref)
+
+        # Skip if we can't find both nodes yet (will be caught later)
+        next unless from_node && to_node
+
+        from_class = from_node.class
+        to_class = to_node.class
+
+        # Look up connection details for each class
+        from_conn_details = model_connections[from_class]
+        to_conn_details = model_connections[to_class]
+
+        # If either class isn't in our mapping, refresh it
+        unless from_conn_details
+          conn = from_class.connection
+          from_conn_details = {
+            adapter: conn.class.name,
+            config: conn.instance_variable_get(:@config),
+            object_id: conn.object_id
+          }
+          model_connections[from_class] = from_conn_details
+        end
+
+        unless to_conn_details
+          conn = to_class.connection
+          to_conn_details = {
+            adapter: conn.class.name,
+            config: conn.instance_variable_get(:@config),
+            object_id: conn.object_id
+          }
+          model_connections[to_class] = to_conn_details
+        end
+
+        # Compare connection details
+        next unless from_conn_details[:object_id] != to_conn_details[:object_id] ||
+                    from_conn_details[:adapter] != to_conn_details[:adapter] ||
+                    from_conn_details[:config][:database] != to_conn_details[:config][:database]
+
+        raise FixtureError, 'Cross-database relationship? Sorry, your data has commitment issues. ' \
+                            "Nodes #{from_ref} (#{from_class}) and #{to_ref} (#{to_class}) use different databases."
+      end
+    end
+
+    # Fetch a node by logical ref.
+    # @param ref [Symbol, String]
+    # @return [Object]
+    def self.[](ref)
+      Registry[ref]
+    end
+  end
+end

data/lib/active_cypher/generators/templates/application_graph_node.rb

@@ -2,4 +2,5 @@
 
 class ApplicationGraphNode < ActiveCypher::Base
   # Adapter‑specific helpers are injected after connection
+  connects_to writing: :primary
 end

data/lib/active_cypher/model/callbacks.rb

@@ -1,29 +1,21 @@
 # frozen_string_literal: true
 
 module ActiveCypher
-  # <= matches your other concerns
   module Model
-    # @!parse
-    #   # Model::Callbacks provides lifecycle hooks for your models, so you can pretend you have control over what happens and when.
-    #   # Because nothing says "enterprise" like a callback firing at just the wrong moment.
-    #   # Under the hood, it’s all just a little bit of Ruby sorcery, callback witchcraft, and the occasional forbidden incantation from the callback crypt.
+    # @note Now containing even more callback-related Ruby sorcery!
     module Callbacks
       extend ActiveSupport::Concern
 
       EVENTS = %i[
-        initialize find validate create update save destroy
+        initialize find create update save destroy
       ].freeze
 
-      included do
-        include ActiveSupport::Callbacks
-        define_callbacks(*EVENTS)
-      end
+      included do |base|
+        base.define_callbacks(*EVENTS)
 
-      class_methods do
         %i[before after around].each do |kind|
           EVENTS.each do |evt|
-            define_method("#{kind}_#{evt}") do |*filters, &block|
-              # This is where the callback coven gathers to cast their hooks.
+            base.define_singleton_method("#{kind}_#{evt}") do |*filters, &block|
               set_callback(evt, kind, *filters, &block)
             end
           end

data/lib/active_cypher/model/connection_handling.rb

@@ -2,73 +2,58 @@
 
 module ActiveCypher
   module Model
-    # Handles connection logic for models, because every ORM needs a way to feel connected.
-    # @note All real connection magic is just Ruby sorcery, a dash of forbidden Ruby incantations, and a sprinkle of ActiveSupport witchcraft.
+    # Handles connection logic for models, because even graph nodes need to feel emotionally wired.
+    # @note Under the hood: it's just Ruby metaprogramming, config keys, and a dash of ActiveSupport pixie dust.
     module ConnectionHandling
       extend ActiveSupport::Concern
 
       class_methods do
-        # Establishes a connection for the model.
-        # Because every model deserves a shot at disappointment.
-        # @note Under the hood, this is just Ruby sorcery and a little forbidden Ruby wizardry to make your config work.
-        def establish_connection(config)
-          cfg = config.symbolize_keys
-
-          # Handle both URL-based and traditional config
-          if cfg[:url]
-            # Use ConnectionUrlResolver for URL-based config
-            resolver = ActiveCypher::ConnectionUrlResolver.new(cfg[:url])
-            resolved_config = resolver.to_hash
+        # Sets up database connections for different roles (e.g., writing, reading, analytics).
+        #
+        # Supports shorthand (just pass a symbol/string for writing role).
+        # If :reading isn’t provided, it defaults to the same DB as :writing. Because DRY is still cool.
+        #
+        # @param mapping [Hash] A role-to-database mapping. Keys are roles, values are DB keys or specs.
+        #   Example:
+        #     connects_to writing: :primary, reading: :replica
+        # @return [void]
+        def connects_to(mapping)
+          mapping = { writing: mapping } if mapping.is_a?(Symbol) || mapping.is_a?(String)
+          symbolized_mapping = mapping.deep_symbolize_keys
 
-            # Merge any additional config options
-            resolved_config = resolved_config.merge(cfg.except(:url)) if resolved_config
+          raise ArgumentError, 'The :writing role must be defined in connects_to mapping.' unless symbolized_mapping.key?(:writing)
 
-            # Bail if URL couldn't be parsed
-            raise ArgumentError, "Invalid connection URL: #{cfg[:url]}" unless resolved_config
+          # If you're lazy and don't specify :reading, it defaults to :writing. You're welcome.
+          symbolized_mapping[:reading] ||= symbolized_mapping[:writing]
 
-            # Get adapter name from resolved config
-            adapter_name = resolved_config[:adapter]
-          else
-            # Traditional config with explicit adapter
-            adapter_name = cfg[:adapter] or raise ArgumentError, 'Missing :adapter'
-            resolved_config = cfg
-          end
+          symbolized_mapping.each do |role, db_key|
+            # db_key can be a symbol (config name) or a nested hash. We’re not judging.
+            spec_name = db_key.is_a?(Hash) ? db_key.values.first : db_key
 
-          path          = "active_cypher/connection_adapters/#{adapter_name}_adapter"
-          class_name    = "#{adapter_name}_adapter".camelize
+            spec = ActiveCypher::CypherConfig.for(spec_name) # Boom. Pulls your DB config.
+            config_for_adapter = spec.dup
 
-          require path
-          adapter_class = ActiveCypher::ConnectionAdapters.const_get(class_name)
-          self.connection = adapter_class.new(resolved_config)
-          connection.connect
-          connection
-        rescue LoadError => e
-          raise AdapterLoadError, "Could not load ActiveCypher adapter '#{adapter_name}' (#{e.message})"
-        end
-
-        # Sets up multiple connections for different roles, because one pool is never enough.
-        # @param mapping [Hash] Role-to-database mapping
-        # @return [void]
-        # Sets up multiple connections for different roles, because one pool is never enough.
-        # @param mapping [Hash] Role-to-database mapping
-        # @return [void]
-        # @note This is where the Ruby gremlins really start dancing—multiple pools, one registry, and a sprinkle of connection witchcraft.
-        def connects_to(mapping)
-          mapping.deep_symbolize_keys.each do |role, db_key|
-            spec = ActiveCypher::CypherConfig.for(db_key) # ← may raise KeyError
-
-            # If spec contains a URL, use ConnectionFactory
+            # If the spec has a URL, parse it and let it override the boring YAML values.
             if spec[:url]
-              factory = ActiveCypher::ConnectionFactory.new(spec[:url])
-              spec = factory.config.merge(spec.except(:url)) if factory.valid?
+              resolver = ActiveCypher::ConnectionUrlResolver.new(spec[:url])
+              url_config = resolver.to_hash
+              raise ArgumentError, "Invalid connection URL: #{spec[:url]}" unless url_config
+
+              config_for_adapter = url_config.merge(spec.except(*url_config.keys))
             end
 
-            pool = ActiveCypher::ConnectionPool.new(spec)
-            connection_handler.set(role.to_sym, :default, pool)
+            # Create a unique connection pool for this role/config combo.
+            pool = ActiveCypher::ConnectionPool.new(config_for_adapter)
+
+            # Register the pool under this spec name.
+            connection_handler.set(spec_name, pool)
           rescue KeyError => e
             raise ActiveCypher::UnknownConnectionError,
-                  "connects_to #{role}: #{db_key.inspect} – #{e.message}"
+                  "connects_to role `#{role}`: database configuration key `#{spec_name.inspect}` not found in cypher_databases.yml – #{e.message}"
           end
+
+          # Save the mapping for later — introspection, debugging, blaming, etc.
+          self.connects_to_mappings = symbolized_mapping
         end
       end
     end

data/lib/active_cypher/model/connection_owner.rb

@@ -3,63 +3,56 @@
 module ActiveCypher
   module Model
     # Mixin for anything that “owns” a connection (nodes, relationships, maybe
-    # graph‑level service objects later). 100 % framework‑agnostic.
-    # @note Because every object wants to feel important by "owning" something, even if it's just a connection.
-    # Moroccan black magick and Ruby sorcery may be involved in keeping these connections alive.
+    # graph‑level service objects later). 100 % framework‑agnostic.
     module ConnectionOwner
       extend ActiveSupport::Concern
       include ActiveCypher::Logging
       include ActiveCypher::Model::ConnectionHandling
 
-      included do
-        # Every class gets its own adapter slot (overridden by establish_connection)
-        # Because nothing says "flexibility" like a class variable you'll forget exists.
-        # This is where the witchcraft happens: sometimes the right connection just appears.
-        cattr_accessor :connection, instance_accessor: false
-      end
-
       class_methods do
-        delegate :current_role, :current_shard,
-                 to: ActiveCypher::RuntimeRegistry
-
         # One handler for all subclasses that include this concern
-        # Because sharing is caring, except when it comes to connection pools.
-        # Summoned by Ruby wizardry: this handler is conjured once and shared by all.
-        @@connection_handler ||= ActiveCypher::ConnectionHandler.new # rubocop:disable Style/ClassVars
-        def connection_handler = @@connection_handler
+        def connection_handler
+          if defined?(@connection_handler) && @connection_handler
+            @connection_handler
+          elsif superclass.respond_to?(:connection_handler)
+            superclass.connection_handler
+          else
+            @connection_handler = ActiveCypher::ConnectionHandler.new
+          end
+        end
 
         # Returns the adapter class being used by this model
-        # @return [Class] The adapter class (e.g., Neo4jAdapter, MemgraphAdapter)
         def adapter_class
-          conn = connection
-          return nil unless conn
-
-          conn.class
+          connection&.class
         end
 
-        # Temporarily switches the current role and shard for the duration of the block.
-        # @param role [Symbol, nil] The role to switch to
-        # @param shard [Symbol] The shard to switch to
-        # @yield The block to execute with the new context
-        # @note Because sometimes you just want to pretend you're connected to something else for a while.
-        # Warning: If you switch too often, you may summon unexpected spirits from the Ruby shadow dimension.
-        def connected_to(role: nil, shard: :default)
-          previous_role  = current_role
-          previous_shard = current_shard
-          ActiveCypher::RuntimeRegistry.current_role  = role  || previous_role
-          ActiveCypher::RuntimeRegistry.current_shard = shard || previous_shard
-          yield
-        ensure
-          ActiveCypher::RuntimeRegistry.current_role  = previous_role
-          ActiveCypher::RuntimeRegistry.current_shard = previous_shard
+        # Always dynamically fetch the connection for the current db_key
+        def connection
+          handler = connection_handler
+
+          if respond_to?(:connects_to_mappings) && connects_to_mappings.is_a?(Hash)
+            db_key = connects_to_mappings[:writing] # Default to :writing mapping
+            if db_key && (pool = handler.pool(db_key))
+              return pool.connection
+            end
+          end
+
+          return superclass.connection if superclass.respond_to?(:connection)
+
+          raise ActiveCypher::ConnectionNotEstablished,
+                "No connection pool found for #{name}, db_key=#{db_key.inspect}"
         end
       end
 
       # Instance method to access the adapter class
-      # @return [Class] The adapter class (e.g., Neo4jAdapter, MemgraphAdapter)
       def adapter_class
         self.class.adapter_class
       end
+
+      # Instance method to access the connection dynamically
+      def connection
+        self.class.connection
+      end
     end
   end
 end

data/lib/active_cypher/model/core.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'active_model'
-
 module ActiveCypher
   module Model
     # Core: The module that tries to make your graph model feel like it belongs in a relational world.
@@ -11,73 +9,13 @@ module ActiveCypher
       extend ActiveSupport::Concern
 
       included do
-        include ActiveModel::API
-        include ActiveModel::Attributes
-        include ActiveModel::Dirty
         include ActiveCypher::Associations
         include ActiveCypher::Scoping
-        include ActiveModel::Validations
 
-        attribute :internal_id, :string
+        attribute :internal_id, :integer
 
-        cattr_accessor :connection, instance_accessor: false
         class_attribute :configurations, instance_accessor: false,
                                          default: ActiveSupport::HashWithIndifferentAccess.new
-
-        # Use array instead of set to preserve insertion order of labels
-        class_attribute :custom_labels, default: []
-      end
-
-      class_methods do
-        # Define a label for the model. Can be called multiple times to add multiple labels.
-        # @param label_name [Symbol, String] The label name
-        # @return [Array] The collection of custom labels
-        #
-        # @example Single label
-        #   class PetNode < ApplicationGraphNode
-        #     label :Pet
-        #   end
-        #
-        # @example Multiple labels
-        #   class PetNode < ApplicationGraphNode
-        #     label :Pet
-        #     label :Animal
-        #   end
-        def label(label_name)
-          # Convert to symbol for consistency
-          label_sym = label_name.to_sym
-
-          # Add to the collection if not already present
-          # Using array to preserve insertion order
-          self.custom_labels = custom_labels.dup << label_sym unless custom_labels.include?(label_sym)
-
-          custom_labels
-        end
-
-        # Get all labels for this model
-        # @return [Array<Symbol>] All labels for this model
-        def labels
-          # Return custom labels if any exist, otherwise use default label
-          custom_labels.empty? ? [default_label] : custom_labels
-        end
-
-        # Returns the primary label for the model
-        # @return [Symbol] The primary label
-        def label_name
-          # Use the first custom label if any exist
-          return custom_labels.first if custom_labels.any?
-
-          # Otherwise fall back to default behavior
-          default_label
-        end
-
-        # Computes the default label for the model based on class name
-        # Strips 'Node' or 'Record' suffix, returns as symbol, capitalized
-        def default_label
-          base = name.split('::').last
-          base = base.sub(/(Node|Record)\z/, '')
-          base.to_sym
-        end
       end
 
       attr_reader :new_record