activecypher 0.12.2 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29fa2252b85c3c67d4f8a8e72acc69ad1021088561ce02c8e1d205bef28b4069
-  data.tar.gz: 0665ef0b5e7a68264f50b846ba78036dc5d3c805e874bc475abb12a3bb699069
+  metadata.gz: 96c24fcfa519e4e44a2e8c8d1e84ae0b975d0d73d25492b025f4968e148a2090
+  data.tar.gz: f9ef843ec7859048e7284731122be13ec519f9d44066471db70db1d4d326198f
 SHA512:
-  metadata.gz: 13b575ead30e4ea3b3476e97993c33e8eebc2dfb788d10e7ad9aa8e02014f389581d3e619f50629611340ea33af2bae967b026cd07110de57586887919ff89f3
-  data.tar.gz: a9dd762af2674169b558739ca5652e21cfcb60adb8a491c5d0bdf22b64a19b45c1087858db972a71f26af9113ee146e67ef57188e6f273adef959ca369a407d3
+  metadata.gz: 0afa400aeab7bfc05a7842cf4361f064b052ec52c8d2fc402da767da882277e8ad1b2c14a2b3c6396c3d34cc436caa45cb43978727d4cd02da80e589af197b10
+  data.tar.gz: e76af4465bdfb80f6b388137e849b2b2705e1f9fd8ae5afd81369f19d40c144819cc5eba6f106677a37932b7a0bbab864951fef2e5fb2450aca982e81971065b

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.13.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(

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activecypher
 version: !ruby/object:Gem::Version
-  version: 0.12.2
+  version: 0.13.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -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