activecypher 0.12.2 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29fa2252b85c3c67d4f8a8e72acc69ad1021088561ce02c8e1d205bef28b4069
-  data.tar.gz: 0665ef0b5e7a68264f50b846ba78036dc5d3c805e874bc475abb12a3bb699069
+  metadata.gz: 614049312045dc138ca5e6aa6950333aa16936ed7f271c0dde0939971b8a4d9d
+  data.tar.gz: 5fd731b9d85a3b45ceb5a27fb08b86904fd4adebe95aeb928cff7da3a4f556b5
 SHA512:
-  metadata.gz: 13b575ead30e4ea3b3476e97993c33e8eebc2dfb788d10e7ad9aa8e02014f389581d3e619f50629611340ea33af2bae967b026cd07110de57586887919ff89f3
-  data.tar.gz: a9dd762af2674169b558739ca5652e21cfcb60adb8a491c5d0bdf22b64a19b45c1087858db972a71f26af9113ee146e67ef57188e6f273adef959ca369a407d3
+  metadata.gz: df907144cb86d4ba2bc10e135a71e38979a91faeaa01b1ed231841626c499f19564dbaf327df5445d7338dd7849b09196fafd42155a20e8abe51397d839c3720
+  data.tar.gz: c4879e2edc165ea074510a759878ae99a95d12e6f74b7d4f21a0846bfcf6eedbbfe08c9ba213211ca748dbcde3e7fc2f4d8720857452376edba5c225a90e32c9

data/lib/active_cypher/connection_adapters/memgraph_adapter.rb

@@ -213,8 +213,13 @@ module ActiveCypher
 
       def protocol_handler_class = ProtocolHandler
 
+      # Memgraph 3.7+ is expected. Earlier versions are untested and may not work.
+      # See: https://memgraph.com/docs for version-specific features.
+      MINIMUM_VERSION = '3.7'
+
       def validate_connection
-        raise ActiveCypher::ConnectionError, "Server at #{config[:uri]} is not Memgraph" unless connection.server_agent.to_s.include?('Memgraph')
+        agent = connection.server_agent.to_s
+        raise ActiveCypher::ConnectionError, "Server at #{config[:uri]} is not Memgraph" unless agent.include?('Memgraph')
 
         true
       end

data/lib/active_cypher/migration.rb

@@ -28,10 +28,26 @@ module ActiveCypher
 
     # DSL ---------------------------------------------------------------
 
-    def create_node_index(label, *props, unique: false, if_not_exists: true, name: nil)
+    # Create a node property index.
+    # @param label [Symbol, String] Node label
+    # @param props [Array<Symbol>] Properties to index
+    # @param unique [Boolean] Create unique index (Neo4j only)
+    # @param if_not_exists [Boolean] Add IF NOT EXISTS clause (Neo4j only)
+    # @param name [String] Index name (Neo4j only)
+    # @param composite [Boolean] Create composite index (Memgraph 3.2+). Default true for multiple props.
+    def create_node_index(label, *props, unique: false, if_not_exists: true, name: nil, composite: nil)
+      # Default composite to true when multiple properties provided
+      composite = props.size > 1 if composite.nil?
+
       cypher = if connection.vendor == :memgraph
-                 # Memgraph syntax: CREATE INDEX ON :Label(prop)
-                 props.map { |p| "CREATE INDEX ON :#{label}(#{p})" }
+                 if composite && props.size > 1
+                   # Memgraph 3.2+ composite index: CREATE INDEX ON :Label(prop1, prop2)
+                   props_list = props.join(', ')
+                   ["CREATE INDEX ON :#{label}(#{props_list})"]
+                 else
+                   # Memgraph single property indexes
+                   props.map { |p| "CREATE INDEX ON :#{label}(#{p})" }
+                 end
                else
                  # Neo4j syntax
                  props_clause = props.map { |p| "n.#{p}" }.join(', ')
@@ -46,10 +62,23 @@ module ActiveCypher
       operations.concat(Array(cypher))
     end
 
-    def create_rel_index(rel_type, *props, if_not_exists: true, name: nil)
+    # Create a relationship property index.
+    # @param rel_type [Symbol, String] Relationship type
+    # @param props [Array<Symbol>] Properties to index
+    # @param if_not_exists [Boolean] Add IF NOT EXISTS clause (Neo4j only)
+    # @param name [String] Index name (Neo4j only)
+    # @param composite [Boolean] Create composite index (Memgraph 3.2+). Default true for multiple props.
+    def create_rel_index(rel_type, *props, if_not_exists: true, name: nil, composite: nil)
+      composite = props.size > 1 if composite.nil?
+
       cypher = if connection.vendor == :memgraph
-                 # Memgraph syntax: CREATE EDGE INDEX ON :REL_TYPE(prop)
-                 props.map { |p| "CREATE EDGE INDEX ON :#{rel_type}(#{p})" }
+                 if composite && props.size > 1
+                   # Memgraph 3.2+ composite edge index
+                   props_list = props.join(', ')
+                   ["CREATE EDGE INDEX ON :#{rel_type}(#{props_list})"]
+                 else
+                   props.map { |p| "CREATE EDGE INDEX ON :#{rel_type}(#{p})" }
+                 end
                else
                  # Neo4j syntax
                  props_clause = props.map { |p| "r.#{p}" }.join(', ')
@@ -99,6 +128,94 @@ module ActiveCypher
       operations.concat(Array(cypher))
     end
 
+    # Create a vector index (Memgraph 3.4+, Neo4j 5.0+).
+    # @param name [String] Index name
+    # @param label [Symbol, String] Node label
+    # @param property [Symbol] Property containing vector embeddings
+    # @param dimension [Integer] Vector dimension (required)
+    # @param metric [Symbol] Distance metric: :cosine, :euclidean, :dot_product (default: :cosine)
+    # @param quantization [Symbol] Quantization type for memory reduction (Memgraph 3.4+): :scalar, nil
+    def create_vector_index(name, label, property, dimension:, metric: :cosine, quantization: nil)
+      cypher = if connection.vendor == :memgraph
+                 config = { dimension: dimension, metric: metric.to_s }
+                 config[:scalar_kind] = 'f32' if quantization == :scalar
+                 config_str = config.map { |k, v| "#{k}: #{v.is_a?(String) ? "'#{v}'" : v}" }.join(', ')
+                 "CREATE VECTOR INDEX #{name} ON :#{label}(#{property}) WITH CONFIG { #{config_str} }"
+               else
+                 # Neo4j syntax
+                 options = { indexConfig: { 'vector.dimensions' => dimension, 'vector.similarity_function' => metric.to_s.upcase } }
+                 opts_str = options.to_json.gsub('"', "'")
+                 "CREATE VECTOR INDEX #{name} IF NOT EXISTS FOR (n:#{label}) ON (n.#{property}) OPTIONS #{opts_str}"
+               end
+      operations << cypher
+    end
+
+    # Create a vector index on relationships (Memgraph 3.4+, Neo4j 2025+).
+    # @param name [String] Index name
+    # @param rel_type [Symbol, String] Relationship type
+    # @param property [Symbol] Property containing vector embeddings
+    # @param dimension [Integer] Vector dimension (required)
+    # @param metric [Symbol] Distance metric: :cosine, :euclidean, :dot_product (default: :cosine)
+    def create_vector_rel_index(name, rel_type, property, dimension:, metric: :cosine)
+      cypher = if connection.vendor == :memgraph
+                 config_str = "dimension: #{dimension}, metric: '#{metric}'"
+                 "CREATE VECTOR EDGE INDEX #{name} ON :#{rel_type}(#{property}) WITH CONFIG { #{config_str} }"
+               else
+                 # Neo4j 2025+ syntax
+                 "CREATE VECTOR INDEX #{name} IF NOT EXISTS FOR ()-[r:#{rel_type}]-() ON (r.#{property}) " \
+                   "OPTIONS { indexConfig: { `vector.dimensions`: #{dimension}, `vector.similarity_function`: '#{metric}' } }"
+               end
+      operations << cypher
+    end
+
+    # Alias for backwards compatibility
+    alias create_vector_edge_index create_vector_rel_index
+
+    # Create a text index on edges (Memgraph 3.6+ only).
+    # Neo4j fulltext indexes on relationships use different syntax via create_fulltext_rel_index.
+    # @param name [String] Index name
+    # @param rel_type [Symbol, String] Relationship type
+    # @param props [Array<Symbol>] Properties to index
+    def create_text_edge_index(name, rel_type, *props)
+      raise NotImplementedError, 'Text edge indexes only supported on Memgraph 3.6+' unless connection.vendor == :memgraph
+
+      props.each do |p|
+        index_name = props.size > 1 ? "#{name}_#{p}" : name.to_s
+        operations << "CREATE TEXT EDGE INDEX #{index_name} ON :#{rel_type}(#{p})"
+      end
+    end
+
+    # Create a fulltext index on relationships (Neo4j only).
+    # @param name [String] Index name
+    # @param rel_type [Symbol, String] Relationship type
+    # @param props [Array<Symbol>] Properties to index
+    # @param if_not_exists [Boolean] Add IF NOT EXISTS clause
+    def create_fulltext_rel_index(name, rel_type, *props, if_not_exists: true)
+      raise NotImplementedError, 'Fulltext relationship indexes only supported on Neo4j' unless connection.vendor == :neo4j
+
+      props_clause = props.map { |p| "r.#{p}" }.join(', ')
+      c = +"CREATE FULLTEXT INDEX #{name}"
+      c << ' IF NOT EXISTS' if if_not_exists
+      c << " FOR ()-[r:#{rel_type}]-() ON EACH [#{props_clause}]"
+      operations << c
+    end
+
+    # Drop all indexes (Memgraph 3.6+ only).
+    # Neo4j requires dropping indexes individually.
+    def drop_all_indexes
+      raise NotImplementedError, 'drop_all_indexes only supported on Memgraph 3.6+' unless connection.vendor == :memgraph
+
+      operations << 'DROP ALL INDEXES'
+    end
+
+    # Drop all constraints (Memgraph 3.6+ only).
+    # Neo4j requires dropping constraints individually.
+    def drop_all_constraints
+      raise NotImplementedError, 'drop_all_constraints only supported on Memgraph 3.6+' unless connection.vendor == :memgraph
+
+      operations << 'DROP ALL CONSTRAINTS'
+    end
+
     def execute(cypher_string)
       operations << cypher_string.strip
     end

data/lib/active_cypher/rails_lens_ext/annotator.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require_relative 'extension'
+
+module ActiveCypher
+  module RailsLensExt
+    # Annotator for ActiveCypher graph models
+    # Discovers and annotates Node and Relationship classes
+    # Uses RailsLens-compatible TOML format and markers
+    class Annotator
+      # Use RailsLens-compatible marker format
+      MARKER_FORMAT = 'rails-lens:graph'
+      ANNOTATION_BEGIN = "# <#{MARKER_FORMAT}:begin>".freeze
+      ANNOTATION_END = "# <#{MARKER_FORMAT}:end>".freeze
+
+      class << self
+        # Annotate all ActiveCypher models
+        # @param options [Hash] Options for annotation
+        # @option options [Boolean] :include_abstract Include abstract classes
+        # @option options [Array<String>] :only Only annotate these models
+        # @option options [Array<String>] :except Skip these models
+        # @return [Hash] Results with :annotated, :skipped, :failed keys
+        def annotate_all(options = {})
+          results = { annotated: [], skipped: [], failed: [] }
+
+          models = discover_models(options)
+
+          models.each do |model|
+            result = annotate_model(model, options)
+            case result[:status]
+            when :annotated
+              results[:annotated] << result
+            when :skipped
+              results[:skipped] << result
+            when :failed
+              results[:failed] << result
+            end
+          end
+
+          results
+        end
+
+        # Remove annotations from all ActiveCypher models
+        # @param options [Hash] Options for removal
+        # @return [Hash] Results with :removed, :skipped keys
+        def remove_all(options = {})
+          results = { removed: [], skipped: [] }
+
+          models = discover_models(options.merge(include_abstract: true))
+
+          models.each do |model|
+            result = remove_annotation(model)
+            if result[:status] == :removed
+              results[:removed] << result
+            else
+              results[:skipped] << result
+            end
+          end
+
+          results
+        end
+
+        # Annotate a single model
+        # @param model [Class] The model class to annotate
+        # @param options [Hash] Options
+        # @return [Hash] Result with :status, :model, :file, :message keys
+        def annotate_model(model, _options = {})
+          file_path = model_file_path(model)
+
+          return { status: :skipped, model: model.name, file: nil, message: 'File not found' } unless file_path && File.exist?(file_path)
+
+          extension = Extension.new(model)
+          annotation = extension.annotate
+
+          return { status: :skipped, model: model.name, file: file_path, message: 'No annotation generated' } unless annotation
+
+          begin
+            write_annotation(file_path, model, annotation)
+            { status: :annotated, model: model.name, file: file_path, message: 'Annotated successfully' }
+          rescue StandardError => e
+            { status: :failed, model: model.name, file: file_path, message: e.message }
+          end
+        end
+
+        # Remove annotation from a single model
+        # @param model [Class] The model class
+        # @return [Hash] Result with :status, :model, :file keys
+        def remove_annotation(model)
+          file_path = model_file_path(model)
+
+          return { status: :skipped, model: model.name, file: nil } unless file_path && File.exist?(file_path)
+
+          content = File.read(file_path)
+
+          if content.include?(ANNOTATION_BEGIN)
+            new_content = ::RailsLens::FileInsertionHelper.remove_after_frozen_string_literal(
+              content, '<rails-lens:graph:begin>', '<rails-lens:graph:end>'
+            )
+            new_content = new_content.gsub(/\n{3,}/, "\n\n")
+
+            File.write(file_path, new_content)
+            { status: :removed, model: model.name, file: file_path }
+          else
+            { status: :skipped, model: model.name, file: file_path }
+          end
+        end
+
+        private
+
+        # Discover all ActiveCypher models
+        def discover_models(options = {})
+          # Eager load all graph models
+          eager_load_graph_models
+
+          models = []
+
+          # Find all Node classes (ActiveCypher::Base descendants)
+          if defined?(::ActiveCypher::Base)
+            ObjectSpace.each_object(Class) do |klass|
+              next unless klass < ::ActiveCypher::Base
+              next if klass == ::ActiveCypher::Base
+
+              models << klass
+            end
+          end
+
+          # Find all Relationship classes (ActiveCypher::Relationship descendants)
+          if defined?(::ActiveCypher::Relationship)
+            ObjectSpace.each_object(Class) do |klass|
+              next unless klass < ::ActiveCypher::Relationship
+              next if klass == ::ActiveCypher::Relationship
+
+              models << klass
+            end
+          end
+
+          # Filter out abstract classes unless requested
+          models.reject! { |m| m.respond_to?(:abstract_class?) && m.abstract_class? } unless options[:include_abstract]
+
+          # Filter by :only option
+          if options[:only]
+            only_names = Array(options[:only]).map(&:to_s)
+            models.select! { |m| only_names.include?(m.name) }
+          end
+
+          # Filter by :except option
+          if options[:except]
+            except_names = Array(options[:except]).map(&:to_s)
+            models.reject! { |m| except_names.include?(m.name) }
+          end
+
+          models.sort_by { |m| m.name || '' }
+        end
+
+        # Eager load graph models from Rails app
+        def eager_load_graph_models
+          return unless defined?(Rails) && Rails.respond_to?(:root)
+
+          # Common paths for graph models
+          graph_paths = [
+            Rails.root.join('app', 'graph'),
+            Rails.root.join('app', 'models', 'graph'),
+            Rails.root.join('app', 'graphs')
+          ]
+
+          graph_paths.each do |path|
+            next unless path.exist?
+
+            Dir.glob(path.join('**', '*.rb')).each do |file|
+              require file
+            rescue LoadError, StandardError => e
+              warn "[ActiveCypher] Failed to load #{file}: #{e.message}"
+            end
+          end
+        end
+
+        # Get the file path for a model
+        def model_file_path(model)
+          # Try const_source_location first (Ruby 2.7+)
+          if model.respond_to?(:const_source_location)
+            location = Object.const_source_location(model.name)
+            return location&.first
+          end
+
+          # Fallback: try to find via instance method
+          if model.instance_methods(false).any?
+            method = model.instance_method(model.instance_methods(false).first)
+            return method.source_location&.first
+          end
+
+          nil
+        rescue StandardError
+          nil
+        end
+
+        # Write annotation to file using RailsLens FileInsertionHelper
+        def write_annotation(file_path, model, annotation)
+          annotation_block = build_annotation_block(annotation)
+
+          ::RailsLens::FileInsertionHelper.insert_at_class_definition(
+            file_path,
+            model.name.split('::').last,
+            annotation_block
+          )
+        end
+
+        # Build the annotation block with markers
+        def build_annotation_block(annotation)
+          lines = [ANNOTATION_BEGIN]
+          annotation.each_line do |line|
+            content = line.chomp
+            lines << (content.empty? ? '#' : "# #{content}")
+          end
+          lines << ANNOTATION_END
+          lines.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/active_cypher/rails_lens_ext/extension.rb

@@ -0,0 +1,409 @@
+# frozen_string_literal: true
+
+# RailsLens extension for ActiveCypher graph models
+# Provides annotation support for Node and Relationship classes
+#
+# This extension detects ActiveCypher models and generates annotations
+# including labels, attributes, associations, and relationship metadata.
+
+begin
+  require 'rails_lens/extensions/base'
+rescue LoadError
+  # RailsLens not available - define a stub Base class
+  module RailsLens
+    module Extensions
+      class Base
+        INTERFACE_VERSION = '1.0'
+
+        class << self
+          def gem_name = raise(NotImplementedError)
+          def detect? = raise(NotImplementedError)
+          def interface_version = INTERFACE_VERSION
+          def compatible? = true
+
+          def gem_available?(name)
+            Gem::Specification.find_by_name(name)
+            true
+          rescue Gem::LoadError
+            false
+          end
+        end
+
+        attr_reader :model_class
+
+        def initialize(model_class)
+          @model_class = model_class
+        end
+
+        def annotate = nil
+        def notes = []
+        def erd_additions = { relationships: [], badges: [], attributes: {} }
+      end
+    end
+  end
+end
+
+module ActiveCypher
+  # RailsLens extension module for annotating ActiveCypher graph models
+  #
+  # Detects and annotates:
+  # - Node classes (inheriting from ActiveCypher::Base)
+  # - Relationship classes (inheriting from ActiveCypher::Relationship)
+  #
+  # Generates annotations for:
+  # - Graph labels
+  # - Attributes with types
+  # - Associations (has_many, belongs_to, has_one)
+  # - Relationship endpoints and types
+  # - Connection configuration
+  module RailsLensExt
+    class Extension < ::RailsLens::Extensions::Base
+      INTERFACE_VERSION = '1.0'
+
+      class << self
+        def gem_name
+          'activecypher'
+        end
+
+        def detect?
+          return false unless gem_available?(gem_name)
+
+          # Ensure ActiveCypher is loaded
+          require 'activecypher' unless defined?(::ActiveCypher::Base)
+          true
+        rescue LoadError
+          false
+        end
+      end
+
+      # Generate annotation string for ActiveCypher models
+      def annotate
+        return nil unless active_cypher_model?
+
+        lines = []
+
+        if node_class?
+          lines.concat(node_annotation_lines)
+        elsif relationship_class?
+          lines.concat(relationship_annotation_lines)
+        end
+
+        return nil if lines.empty?
+
+        lines.join("\n")
+      end
+
+      # Generate analysis notes for best practices
+      def notes
+        return [] unless active_cypher_model?
+
+        notes = []
+
+        if node_class?
+          notes.concat(node_notes)
+        elsif relationship_class?
+          notes.concat(relationship_notes)
+        end
+
+        notes
+      end
+
+      # Generate ERD additions for graph visualization
+      def erd_additions
+        return default_erd_additions unless active_cypher_model?
+
+        if node_class?
+          node_erd_additions
+        elsif relationship_class?
+          relationship_erd_additions
+        else
+          default_erd_additions
+        end
+      end
+
+      private
+
+      def default_erd_additions
+        { relationships: [], badges: [], attributes: {} }
+      end
+
+      # ============================================================
+      # Detection Methods
+      # ============================================================
+
+      def active_cypher_model?
+        node_class? || relationship_class?
+      end
+
+      def node_class?
+        return false unless defined?(::ActiveCypher::Base)
+
+        model_class < ::ActiveCypher::Base
+      rescue StandardError
+        false
+      end
+
+      def relationship_class?
+        return false unless defined?(::ActiveCypher::Relationship)
+
+        model_class < ::ActiveCypher::Relationship
+      rescue StandardError
+        false
+      end
+
+      def abstract_class?
+        model_class.respond_to?(:abstract_class?) && model_class.abstract_class?
+      end
+
+      # ============================================================
+      # Node Annotation (TOML format)
+      # ============================================================
+
+      def node_annotation_lines
+        lines = []
+        lines << 'model_type = "node"'
+        lines << 'abstract = true' if abstract_class?
+
+        # Labels
+        if model_class.respond_to?(:labels) && model_class.labels.any?
+          labels = model_class.labels.map { |l| "\"#{l}\"" }.join(', ')
+          lines << "labels = [#{labels}]"
+        end
+
+        # Attributes
+        lines.concat(attribute_lines)
+
+        # Associations
+        lines.concat(association_lines) if model_class.respond_to?(:_reflections)
+
+        # Connection info
+        lines.concat(connection_lines)
+
+        lines
+      end
+
+      # ============================================================
+      # Relationship Annotation (TOML format)
+      # ============================================================
+
+      def relationship_annotation_lines
+        lines = []
+        lines << 'model_type = "relationship"'
+        lines << 'abstract = true' if abstract_class?
+
+        # Relationship type
+        lines << "type = \"#{model_class.relationship_type}\"" if model_class.respond_to?(:relationship_type) && model_class.relationship_type
+
+        # Endpoints
+        lines << "from_class = \"#{model_class.from_class_name}\"" if model_class.respond_to?(:from_class_name) && model_class.from_class_name
+
+        lines << "to_class = \"#{model_class.to_class_name}\"" if model_class.respond_to?(:to_class_name) && model_class.to_class_name
+
+        # Node base class (for connection delegation)
+        lines << "node_base_class = \"#{model_class._node_base_class.name}\"" if model_class.respond_to?(:node_base_class) && model_class._node_base_class
+
+        # Attributes
+        lines.concat(attribute_lines)
+
+        # Connection info
+        lines.concat(connection_lines)
+
+        lines
+      end
+
+      # ============================================================
+      # Shared Annotation Helpers (TOML format)
+      # ============================================================
+
+      def attribute_lines
+        lines = []
+
+        return lines unless model_class.respond_to?(:attribute_types)
+
+        attrs = model_class.attribute_types.except('internal_id')
+        return lines if attrs.empty?
+
+        lines << ''
+        attr_entries = attrs.map do |name, type|
+          type_name = type.class.name.demodulize.underscore.sub(/_type$/, '')
+          "{ name = \"#{name}\", type = \"#{type_name}\" }"
+        end
+        lines << "attributes = [#{attr_entries.join(', ')}]"
+
+        lines
+      end
+
+      def association_lines
+        lines = []
+        reflections = model_class._reflections
+
+        return lines if reflections.empty?
+
+        lines << ''
+        lines << '[associations]'
+
+        reflections.each do |name, opts|
+          macro = opts[:macro]
+          target = opts[:class_name]
+          rel_type = opts[:relationship]
+          direction = opts[:direction]
+
+          parts = ["macro = \"#{macro}\""]
+          parts << "class = \"#{target}\"" if target
+          parts << "rel = \"#{rel_type}\"" if rel_type
+          parts << "direction = \"#{direction}\"" if direction && direction != :out
+
+          if opts[:through]
+            parts << "through = \"#{opts[:through]}\""
+            parts << "source = \"#{opts[:source]}\"" if opts[:source]
+          end
+
+          parts << "relationship_class = \"#{opts[:relationship_class]}\"" if opts[:relationship_class]
+
+          lines << "#{name} = { #{parts.join(', ')} }"
+        end
+
+        lines
+      end
+
+      def connection_lines
+        lines = []
+
+        return lines unless model_class.respond_to?(:connects_to_mappings)
+
+        mappings = model_class.connects_to_mappings
+        return lines if mappings.nil? || mappings.empty?
+
+        lines << ''
+        lines << '[connection]'
+
+        mappings.each do |role, db_key|
+          lines << "#{role} = \"#{db_key}\""
+        end
+
+        lines
+      end
+
+      # ============================================================
+      # Node Notes (Best Practices)
+      # ============================================================
+
+      def node_notes
+        notes = []
+
+        # Check for missing labels
+        notes << "[activecypher] #{model_class.name}: No labels defined" if model_class.respond_to?(:labels) && model_class.labels.empty?
+
+        # Check for models without attributes (besides internal_id)
+        if model_class.respond_to?(:attribute_types)
+          user_attrs = model_class.attribute_types.except('internal_id')
+          notes << "[activecypher] #{model_class.name}: No attributes defined" if user_attrs.empty? && !abstract_class?
+        end
+
+        # Check for potential N+1 patterns in associations
+        if model_class.respond_to?(:_reflections)
+          has_many_count = model_class._reflections.count { |_, r| r[:macro] == :has_many }
+          notes << "[activecypher] #{model_class.name}: #{has_many_count} has_many associations - consider eager loading" if has_many_count > 3
+        end
+
+        notes
+      end
+
+      # ============================================================
+      # Relationship Notes (Best Practices)
+      # ============================================================
+
+      def relationship_notes
+        notes = []
+
+        # Check for missing endpoints
+        unless abstract_class?
+          if !model_class.respond_to?(:from_class_name) || model_class.from_class_name.nil?
+            notes << "[activecypher] #{model_class.name}: Missing from_class definition"
+          end
+
+          if !model_class.respond_to?(:to_class_name) || model_class.to_class_name.nil?
+            notes << "[activecypher] #{model_class.name}: Missing to_class definition"
+          end
+
+          if !model_class.respond_to?(:relationship_type) || model_class.relationship_type.nil?
+            notes << "[activecypher] #{model_class.name}: Missing relationship type definition"
+          end
+        end
+
+        notes
+      end
+
+      # ============================================================
+      # ERD Additions
+      # ============================================================
+
+      def node_erd_additions
+        badges = ['graph-node']
+        badges << 'abstract' if abstract_class?
+
+        relationships = []
+
+        # Add relationships from associations
+        if model_class.respond_to?(:_reflections)
+          model_class._reflections.each_value do |opts|
+            rel = {
+              type: opts[:macro].to_s,
+              from: model_class.name,
+              to: opts[:class_name],
+              label: opts[:relationship],
+              style: opts[:macro] == :has_many ? 'solid' : 'dashed',
+              direction: opts[:direction]
+            }
+            relationships << rel
+          end
+        end
+
+        {
+          relationships: relationships,
+          badges: badges,
+          attributes: {
+            model_type: 'node',
+            labels: model_class.respond_to?(:labels) ? model_class.labels : []
+          }
+        }
+      end
+
+      def relationship_erd_additions
+        badges = ['graph-relationship']
+        badges << 'abstract' if abstract_class?
+
+        relationships = []
+
+        # Add the relationship edge
+        if model_class.respond_to?(:from_class_name) &&
+           model_class.respond_to?(:to_class_name) &&
+           model_class.from_class_name &&
+           model_class.to_class_name
+
+          relationships << {
+            type: 'edge',
+            from: model_class.from_class_name,
+            to: model_class.to_class_name,
+            label: model_class.relationship_type || 'RELATED',
+            style: 'bold',
+            model: model_class.name
+          }
+        end
+
+        {
+          relationships: relationships,
+          badges: badges,
+          attributes: {
+            model_type: 'relationship',
+            relationship_type: model_class.respond_to?(:relationship_type) ? model_class.relationship_type : nil
+          }
+        }
+      end
+    end
+  end
+
+  # Register the extension with RailsLens for gem-based auto-discovery
+  # RailsLens looks for GemName::RailsLensExtension constant
+  RailsLensExtension = RailsLensExt::Extension
+end

data/lib/active_cypher/rails_lens_ext/model_source.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Only define model source if RailsLens is available
+# This file is loaded conditionally via railtie, not via autoload
+return unless defined?(RailsLens::ModelSource)
+
+require_relative 'annotator'
+
+module ActiveCypher
+  module RailsLensExt
+    # Model source for ActiveCypher graph models
+    # Provides integration with RailsLens annotation system
+    class ModelSource < ::RailsLens::ModelSource
+      class << self
+        def models(options = {})
+          Annotator.send(:discover_models, options)
+        end
+
+        def file_patterns
+          ['app/graph/**/*.rb', 'app/models/graph/**/*.rb', 'app/graphs/**/*.rb']
+        end
+
+        def annotate_model(model, options = {})
+          Annotator.annotate_model(model, options)
+        end
+
+        def remove_annotation(model)
+          Annotator.remove_annotation(model)
+        end
+
+        def source_name
+          'ActiveCypher Graph'
+        end
+      end
+    end
+  end
+
+  # Register for auto-discovery by RailsLens (for gems with conventional names)
+  RailsLensModelSource = RailsLensExt::ModelSource
+
+  # Explicitly register with RailsLens (gem name 'activecypher' doesn't match 'ActiveCypher')
+  ::RailsLens::ModelSourceLoader.register(RailsLensExt::ModelSource)
+end

data/lib/active_cypher/railtie.rb

@@ -60,6 +60,11 @@ module ActiveCypher
       end
     end
 
+    # Load RailsLens integration if RailsLens is available
+    initializer 'active_cypher.rails_lens_integration', after: :load_config_initializers do
+      require 'active_cypher/rails_lens_ext/model_source' if defined?(::RailsLens::ModelSource)
+    end
+
     generators do
       require 'active_cypher/generators/install_generator'
       require 'active_cypher/generators/node_generator'
@@ -70,6 +75,7 @@ module ActiveCypher
     rake_tasks do
       load File.expand_path('../tasks/graphdb_migrate.rake', __dir__)
       load File.expand_path('../tasks/graphdb_schema.rake', __dir__)
+      # Standalone annotation task no longer needed - RailsLens handles it
     end
   end
 end

data/lib/active_cypher/relationship.rb

@@ -129,6 +129,10 @@ module ActiveCypher
       # Prevent subclasses from overriding node_base_class
       def inherited(subclass)
         super
+        # Reset abstract_class for subclasses (mirrors Model::Abstract behavior
+        # which gets overridden by this method definition)
+        subclass.abstract_class = false
+
         return unless _node_base_class
 
         subclass._node_base_class = _node_base_class

data/lib/active_cypher/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module ActiveCypher
-  VERSION = '0.12.2'
+  VERSION = '0.14.0'
 
   def self.gem_version
     Gem::Version.new VERSION

data/lib/activecypher.rb

@@ -100,6 +100,7 @@ loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
 loader.ignore("#{__dir__}/active_cypher/version.rb")
 loader.ignore("#{__dir__}/active_cypher/railtie.rb")
 loader.ignore("#{__dir__}/active_cypher/generators")
+loader.ignore("#{__dir__}/active_cypher/rails_lens_ext")
 loader.ignore("#{__dir__}/activecypher.rb")
 loader.ignore("#{__dir__}/cyrel.rb")
 loader.inflector.inflect(

data/lib/cyrel/expression/exists.rb

@@ -35,5 +35,38 @@ module Cyrel
         "EXISTS(#{rendered_pattern})"
       end
     end
+
+    # Represents an EXISTS { MATCH ... WHERE ... } subquery predicate (Memgraph 3.5+).
+    # Allows full subquery syntax inside EXISTS block.
+    #
+    # @example
+    #   Cyrel.exists_block { match(Cyrel.node(:a) > Cyrel.rel(:r) > Cyrel.node(:b)); where(Cyrel.prop(:b, :active) == true) }
+    #   # => EXISTS { MATCH (a)-[r]->(b) WHERE b.active = $p1 }
+    class ExistsBlock < Base
+      attr_reader :subquery
+
+      # @param subquery [Cyrel::Query] A query object representing the subquery.
+      def initialize(subquery)
+        raise ArgumentError, 'ExistsBlock requires a Cyrel::Query' unless subquery.is_a?(Cyrel::Query)
+
+        @subquery = subquery
+      end
+
+      # Renders the EXISTS { ... } expression.
+      # @param query [Cyrel::Query] The parent query for parameter merging.
+      # @return [String] The Cypher string fragment.
+      def render(query)
+        inner_cypher, inner_params = @subquery.to_cypher
+
+        # Merge subquery parameters into the parent query
+        # The inner query uses its own parameter keys, we need to register values
+        # which will get new keys in the parent query
+        inner_params.each_value do |value|
+          query.register_parameter(value)
+        end
+
+        "EXISTS { #{inner_cypher} }"
+      end
+    end
   end
 end

data/lib/cyrel/pattern/node.rb

@@ -12,14 +12,16 @@ module Cyrel
 
       attribute :alias_name, Cyrel::Types::SymbolType.new
       attribute :labels,     array: :string, default: []
+      attribute :or_labels,  array: :string, default: []  # Memgraph 3.2+: (n:Label1|Label2)
       attribute :properties, Cyrel::Types::HashType.new, default: -> { {} }
 
       validates :alias_name, presence: true
 
-      def initialize(alias_name, labels: nil, properties: {}, **kw)
+      def initialize(alias_name, labels: nil, or_labels: nil, properties: {}, **kw)
         super(
           { alias_name: alias_name,
             labels: Array(labels).compact.flatten,
+            or_labels: Array(or_labels).compact.flatten,
             properties: properties }.merge(kw)
         )
       end
@@ -38,7 +40,14 @@ module Cyrel
 
       def render(query)
         base = +"(#{alias_name}"
-        base << ':' << labels.join(':') unless labels.empty?
+
+        # OR labels take precedence (Memgraph 3.2+: n:Label1|Label2)
+        if or_labels.any?
+          base << ':' << or_labels.join('|')
+        elsif labels.any?
+          base << ':' << labels.join(':')
+        end
+
         unless properties.empty?
           params = properties.with_indifferent_access
           formatted = params.map do |k, v|
@@ -60,6 +69,7 @@ module Cyrel
       def freeze
         super
         labels.freeze
+        or_labels.freeze
         properties.freeze
       end
 

data/lib/cyrel.rb

@@ -11,8 +11,9 @@ module Cyrel
 
   # Cyrel DSL helper: alias for node creation.
   # Example: Cyrel.n(:person, :Person, name: 'Alice')
-  def n(alias_name = nil, *labels, **properties)
-    Pattern::Node.new(alias_name, labels: labels, properties: properties)
+  # Example: Cyrel.n(:n, or_labels: [:Person, :Organization])  # Memgraph 3.2+
+  def n(alias_name = nil, *labels, or_labels: nil, **properties)
+    Pattern::Node.new(alias_name, labels: labels, or_labels: or_labels, properties: properties)
   end
 
   # Cyrel DSL helper: creates a CALL clause for a procedure.
@@ -29,8 +30,9 @@ module Cyrel
 
   # Cyrel DSL helper: creates a node pattern.
   # Example: Cyrel.node(:n, :Person, name: 'Alice')
-  def node(alias_name = nil, *labels, **properties)
-    Pattern::Node.new(alias_name, labels: labels, properties: properties)
+  # Example: Cyrel.node(:n, or_labels: [:Person, :Organization])  # Memgraph 3.2+
+  def node(alias_name = nil, *labels, or_labels: nil, **properties)
+    Pattern::Node.new(alias_name, labels: labels, or_labels: or_labels, properties: properties)
   end
 
   # Cyrel DSL helper: creates a relationship pattern.
@@ -57,14 +59,14 @@ module Cyrel
       @pending_direction = nil
     end
 
-    def node(alias_name = nil, *labels, **properties)
+    def node(alias_name = nil, *labels, or_labels: nil, **properties)
       # If there's a pending direction, we need to add a relationship first
       if @pending_direction && @elements.any? && @elements.last.is_a?(Cyrel::Pattern::Node)
         @elements << Cyrel::Pattern::Relationship.new(types: [], direction: @pending_direction)
         @pending_direction = nil
       end
 
-      n = Cyrel::Pattern::Node.new(alias_name, labels: labels, properties: properties)
+      n = Cyrel::Pattern::Node.new(alias_name, labels: labels, or_labels: or_labels, properties: properties)
       @elements << n
       self
     end
@@ -250,6 +252,16 @@ module Cyrel
     Expression.exists(pattern)
   end
 
+  # Cyrel DSL helper: creates an EXISTS block with full subquery (Memgraph 3.5+).
+  # Example:
+  #   Cyrel.exists_block { match(Cyrel.node(:a) > Cyrel.rel(:r) > Cyrel.node(:b, :Admin)) }
+  #   # => EXISTS { MATCH (a)-[r]->(b:Admin) }
+  def exists_block(&block)
+    subquery = Query.new
+    subquery.instance_eval(&block)
+    Expression::ExistsBlock.new(subquery)
+  end
+
   # Cyrel DSL helper: creates a Logical NOT expression.
   # Example: Cyrel.not(expression)
   def not(expression)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activecypher
 version: !ruby/object:Gem::Version
-  version: 0.12.2
+  version: 0.14.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -43,14 +43,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.11.0
+        version: 0.11.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.11.0
+        version: 0.11.1
 - !ruby/object:Gem::Dependency
   name: io-endpoint
   requirement: !ruby/object:Gem::Requirement
@@ -107,6 +107,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails_lens
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: OpenCypher Adapter ala ActiveRecord
 email:
 - seuros@pre-history.com
@@ -171,6 +185,9 @@ files:
 - lib/active_cypher/model/labelling.rb
 - lib/active_cypher/model/persistence.rb
 - lib/active_cypher/model/querying.rb
+- lib/active_cypher/rails_lens_ext/annotator.rb
+- lib/active_cypher/rails_lens_ext/extension.rb
+- lib/active_cypher/rails_lens_ext/model_source.rb
 - lib/active_cypher/railtie.rb
 - lib/active_cypher/redaction.rb
 - lib/active_cypher/relation.rb