rails-flow-map 0.1.0

data/lib/rails_flow_map/formatters/sequence_formatter.rb

@@ -0,0 +1,288 @@
+module RailsFlowMap
+  # Generates sequence diagrams showing request flow through the application
+  #
+  # This formatter creates Mermaid sequence diagrams that visualize how requests
+  # flow through controllers, services, models, and the database. It can optionally
+  # include middleware, callbacks, and validation steps.
+  #
+  # @example Basic usage
+  #   formatter = SequenceFormatter.new(graph, endpoint: '/api/users')
+  #   diagram = formatter.format
+  #
+  # @example With all features enabled
+  #   formatter = SequenceFormatter.new(graph, {
+  #     endpoint: '/api/users',
+  #     include_middleware: true,
+  #     include_callbacks: true,
+  #     include_validations: true,
+  #     include_database: true
+  #   })
+  #
+  class SequenceFormatter
+      # Creates a new sequence diagram formatter
+      #
+      # @param graph [FlowGraph] The graph to analyze
+      # @param options [Hash] Configuration options
+      # @option options [String] :endpoint The endpoint to analyze (analyzes all if nil)
+      # @option options [Boolean] :include_middleware Include middleware in diagram (default: false)
+      # @option options [Boolean] :include_callbacks Include callbacks in diagram (default: false)
+      # @option options [Boolean] :include_validations Include validations in diagram (default: false)
+      # @option options [Boolean] :include_database Include database queries in diagram (default: true)
+      def initialize(graph, options = {})
+        @graph = graph
+        @endpoint = options[:endpoint]
+        @include_middleware = options[:include_middleware] || false
+        @include_callbacks = options[:include_callbacks] || false
+        @include_validations = options[:include_validations] || false
+        @include_database = options[:include_database] || true
+      end
+
+      # Generates the sequence diagram
+      #
+      # @param graph [FlowGraph] Optional graph to format (uses instance graph by default)
+      # @return [String] Mermaid sequence diagram markup
+      def format(graph = @graph)
+        output = []
+        output << "```mermaid"
+        output << "sequenceDiagram"
+        output << "    autonumber"
+        
+        # 参加者の定義
+        output.concat(define_participants(graph))
+        
+        # エンドポイントに関連するノードを取得
+        route_nodes = filter_route_nodes(graph)
+        
+        if route_nodes.empty?
+          output << "    Note over Client: No routes found for endpoint: #{@endpoint}"
+        else
+          route_nodes.each do |route|
+            output << ""
+            output << "    Note over Client: === #{route.attributes[:verb]} #{route.attributes[:path]} ==="
+            output.concat(generate_sequence_for_route(route, graph))
+          end
+        end
+        
+        output << "```"
+        output.join("\n")
+      end
+
+      private
+
+      def define_participants(graph)
+        participants = ["    participant Client", "    participant Router"]
+        
+        if @include_middleware
+          participants << "    participant Middleware"
+        end
+        
+        # コントローラーの追加
+        controllers = graph.nodes_by_type(:controller).map(&:name).uniq
+        controllers.each do |controller|
+          participants << "    participant #{sanitize_name(controller)}"
+        end
+        
+        # サービスの追加
+        services = graph.nodes_by_type(:service).map(&:name).uniq
+        services.each do |service|
+          participants << "    participant #{sanitize_name(service)}"
+        end
+        
+        # モデルの追加
+        models = graph.nodes_by_type(:model).map(&:name).uniq
+        models.each do |model|
+          participants << "    participant #{sanitize_name(model)}"
+        end
+        
+        if @include_database
+          participants << "    participant Database"
+        end
+        
+        participants
+      end
+
+      def filter_route_nodes(graph)
+        route_nodes = graph.nodes_by_type(:route)
+        
+        if @endpoint
+          # エンドポイントの正確なマッチング
+          route_nodes = route_nodes.select do |node|
+            path = node.attributes[:path]
+            path == @endpoint || path&.gsub(/:[\w_]+/, '*') == @endpoint.gsub(/\d+/, '*')
+          end
+        end
+        
+        route_nodes
+      end
+
+      def generate_sequence_for_route(route, graph)
+        lines = []
+        
+        # ミドルウェア処理
+        if @include_middleware
+          lines << "    Client->>Router: #{route.attributes[:verb]} #{route.attributes[:path]}"
+          lines << "    Router->>Middleware: Process request"
+          lines << "    activate Middleware"
+          lines << "    Note right of Middleware: Authentication<br/>CORS<br/>Rate limiting"
+          lines << "    Middleware->>Router: Continue"
+          lines << "    deactivate Middleware"
+        else
+          lines << "    Client->>+Router: #{route.attributes[:verb]} #{route.attributes[:path]}"
+        end
+        
+        # ルートからアクションへの処理
+        route_edges = graph.edges.select { |e| e.from == route.id && e.type == :routes_to }
+        
+        route_edges.each do |edge|
+          action = graph.find_node(edge.to)
+          next unless action
+          
+          controller_name = sanitize_name(action.attributes[:controller] || "Controller")
+          
+          # コントローラーアクションの開始
+          lines << "    Router->>+#{controller_name}: #{action.name}(params)"
+          
+          # コールバック処理
+          if @include_callbacks
+            lines << "    activate #{controller_name}"
+            lines << "    Note over #{controller_name}: before_action callbacks"
+          end
+          
+          # バリデーション
+          if @include_validations && ['create', 'update'].include?(action.name)
+            lines << "    #{controller_name}->>#{controller_name}: validate_params"
+            lines << "    alt Invalid parameters"
+            lines << "        #{controller_name}-->>Client: 422 Unprocessable Entity"
+            lines << "    else Valid parameters"
+          end
+          
+          # サービス呼び出し
+          lines.concat(generate_service_calls(action, controller_name, graph))
+          
+          # バリデーションの終了
+          if @include_validations && ['create', 'update'].include?(action.name)
+            lines << "    end"
+          end
+          
+          # レスポンスの生成
+          lines << "    #{controller_name}->>#{controller_name}: render_response"
+          
+          # コールバック処理の終了
+          if @include_callbacks
+            lines << "    Note over #{controller_name}: after_action callbacks"
+            lines << "    deactivate #{controller_name}"
+          end
+          
+          # クライアントへのレスポンス
+          lines << "    #{controller_name}-->>-Router: Response data"
+          lines << "    Router-->>-Client: #{generate_response_code(action.name)} {data}"
+        end
+        
+        lines
+      end
+
+      def generate_service_calls(action, controller_name, graph)
+        lines = []
+        
+        # アクションからサービスへの呼び出し
+        service_edges = graph.edges.select { |e| e.from == action.id && e.type == :calls_service }
+        
+        service_edges.each_with_index do |service_edge, index|
+          service = graph.find_node(service_edge.to)
+          next unless service
+          
+          service_name = sanitize_name(service.name)
+          method_name = service_edge.label || "process"
+          
+          # サービスメソッドの呼び出し
+          lines << "    #{controller_name}->>+#{service_name}: #{method_name}(params)"
+          
+          # サービス内の処理
+          lines << "    activate #{service_name}"
+          lines << "    Note over #{service_name}: Business logic"
+          
+          # モデルアクセス
+          lines.concat(generate_model_access(service, service_name, graph))
+          
+          # サービスからのレスポンス
+          lines << "    deactivate #{service_name}"
+          lines << "    #{service_name}-->>-#{controller_name}: ServiceResult"
+          
+          # エラーハンドリング
+          if index == 0  # 最初のサービス呼び出しのみ
+            lines << "    alt Service error"
+            lines << "        #{controller_name}-->>Client: 500 Internal Server Error"
+            lines << "    else Success"
+          end
+        end
+        
+        # エラーハンドリングの終了
+        if service_edges.any?
+          lines << "    end"
+        end
+        
+        lines
+      end
+
+      def generate_model_access(service, service_name, graph)
+        lines = []
+        
+        # サービスからモデルへのアクセス
+        model_edges = graph.edges.select { |e| e.from == service.id && e.type == :accesses_model }
+        
+        model_edges.each do |model_edge|
+          model = graph.find_node(model_edge.to)
+          next unless model
+          
+          model_name = sanitize_name(model.name)
+          query = model_edge.label || "query"
+          
+          # モデルへのクエリ
+          lines << "    #{service_name}->>+#{model_name}: #{query}"
+          
+          # データベースアクセス
+          if @include_database
+            lines << "    #{model_name}->>+Database: SQL Query"
+            lines << "    Note right of Database: SELECT * FROM #{model_name.downcase}s<br/>WHERE ..."
+            lines << "    Database-->>-#{model_name}: ResultSet"
+          else
+            lines << "    activate #{model_name}"
+            lines << "    Note over #{model_name}: Database query"
+            lines << "    deactivate #{model_name}"
+          end
+          
+          # モデルからの結果
+          lines << "    #{model_name}-->>-#{service_name}: [#{model_name} objects]"
+        end
+        
+        # 関連モデルの読み込み
+        if model_edges.any? && @include_database
+          lines << "    Note over #{service_name}: Load associations (N+1 prevention)"
+        end
+        
+        lines
+      end
+
+      def generate_response_code(action_name)
+        case action_name
+        when 'index', 'show'
+          '200 OK'
+        when 'create'
+          '201 Created'
+        when 'update'
+          '200 OK'
+        when 'destroy'
+          '204 No Content'
+        else
+          '200 OK'
+        end
+      end
+
+      def sanitize_name(name)
+        # Mermaidで使用できない文字を置換
+        sanitized = name.to_s.gsub(/[^a-zA-Z0-9_]/, '_').gsub(/^_+|_+$/, '')
+        # 空文字列になった場合はデフォルト値を返す
+        sanitized.empty? ? "node_#{name.hash.abs}" : sanitized
+      end
+  end
+end

data/lib/rails_flow_map/generators/install/templates/rails_flow_map.rb

@@ -0,0 +1,34 @@
+# RailsFlowMap configuration
+#
+# This initializer allows you to configure RailsFlowMap behavior
+# You can customize the analysis and output options here
+
+RailsFlowMap.configure do |config|
+  # Directories to exclude from analysis
+  # config.exclude_paths = ['app/models/concerns', 'app/controllers/concerns']
+  
+  # Model files pattern (default: app/models/**/*.rb)
+  # config.model_pattern = 'app/models/**/*.rb'
+  
+  # Controller files pattern (default: app/controllers/**/*.rb)
+  # config.controller_pattern = 'app/controllers/**/*.rb'
+  
+  # Default output format (mermaid, plantuml, graphviz)
+  # config.default_format = :mermaid
+  
+  # Default output directory
+  # config.output_directory = 'doc/flow_maps'
+  
+  # Include STI (Single Table Inheritance) relationships
+  # config.include_sti = true
+  
+  # Include polymorphic relationships
+  # config.include_polymorphic = true
+  
+  # Custom node colors (for Mermaid format)
+  # config.node_colors = {
+  #   model: '#f9f',
+  #   controller: '#bbf',
+  #   action: '#bfb'
+  # }
+end

data/lib/rails_flow_map/generators/install_generator.rb

@@ -0,0 +1,32 @@
+require 'rails/generators/base'
+
+module RailsFlowMap
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+      
+      desc "Creates a RailsFlowMap initializer"
+      
+      def create_initializer_file
+        template "rails_flow_map.rb", "config/initializers/rails_flow_map.rb"
+      end
+      
+      def create_output_directory
+        empty_directory "doc/flow_maps"
+        create_file "doc/flow_maps/.gitkeep"
+      end
+      
+      def display_post_install_message
+        say "\nRailsFlowMap has been successfully installed!", :green
+        say "\nAvailable rake tasks:"
+        say "  rake rails_flow_map:generate       # Generate complete flow map"
+        say "  rake rails_flow_map:models         # Generate model relationships"
+        say "  rake rails_flow_map:controllers    # Generate controller/action flow"
+        say "  rake rails_flow_map:formats        # List available formats"
+        say "\nExample usage:"
+        say "  rake rails_flow_map:generate[mermaid,doc/flow_maps/app_flow.md]"
+        say "\nFlow maps will be saved in doc/flow_maps/ by default."
+      end
+    end
+  end
+end

data/lib/rails_flow_map/logging.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module RailsFlowMap
+  # Centralized logging functionality for RailsFlowMap
+  #
+  # This module provides a standardized logging interface across all components
+  # of the RailsFlowMap gem. It supports configurable log levels, structured
+  # logging, and automatic context inclusion.
+  #
+  # @example Basic usage
+  #   RailsFlowMap::Logging.logger.info("Processing graph with 10 nodes")
+  #
+  # @example With context
+  #   RailsFlowMap::Logging.with_context(formatter: 'MermaidFormatter') do
+  #     RailsFlowMap::Logging.logger.debug("Starting format operation")
+  #   end
+  #
+  # @example Error logging with context
+  #   begin
+  #     risky_operation
+  #   rescue => e
+  #     RailsFlowMap::Logging.log_error(e, context: { operation: 'export' })
+  #   end
+  module Logging
+    extend self
+
+    # Custom formatter for structured log output
+    class StructuredFormatter < Logger::Formatter
+      def call(severity, time, progname, msg)
+        context = Thread.current[:rails_flow_map_context] || {}
+        context_str = context.empty? ? '' : " [#{context.map { |k, v| "#{k}=#{v}" }.join(', ')}]"
+        
+        "[#{time.strftime('%Y-%m-%d %H:%M:%S')}] #{severity}#{context_str}: #{msg}\n"
+      end
+    end
+
+    # Custom log levels for domain-specific logging
+    CUSTOM_LEVELS = {
+      security: Logger::WARN,
+      performance: Logger::INFO,
+      graph_analysis: Logger::DEBUG
+    }.freeze
+
+    # @return [Logger] The shared logger instance
+    def logger
+      @logger ||= create_logger
+    end
+
+    # Sets a custom logger instance
+    #
+    # @param custom_logger [Logger] The logger to use
+    def logger=(custom_logger)
+      @logger = custom_logger
+    end
+
+    # Log an error with full context and backtrace
+    #
+    # @param error [Exception] The error to log
+    # @param context [Hash] Additional context information
+    # @param level [Symbol] Log level (:error, :warn, :info, :debug)
+    def log_error(error, context: {}, level: :error)
+      error_context = {
+        error_class: error.class.name,
+        error_message: error.message,
+        **context
+      }
+
+      with_context(error_context) do
+        logger.send(level, "#{error.class}: #{error.message}")
+        
+        if error.backtrace && logger.level <= Logger::DEBUG
+          logger.debug("Backtrace:\n#{error.backtrace.join("\n")}")
+        end
+      end
+    end
+
+    # Execute a block with additional logging context
+    #
+    # @param context [Hash] Context to add to all log messages in the block
+    # @yield The block to execute with context
+    def with_context(context = {})
+      old_context = Thread.current[:rails_flow_map_context] || {}
+      Thread.current[:rails_flow_map_context] = old_context.merge(context)
+      
+      yield
+    ensure
+      Thread.current[:rails_flow_map_context] = old_context
+    end
+
+    # Log a performance metric
+    #
+    # @param operation [String] Name of the operation
+    # @param duration [Float] Duration in seconds
+    # @param additional_metrics [Hash] Additional metrics to log
+    def log_performance(operation, duration, additional_metrics = {})
+      return unless logger.level <= CUSTOM_LEVELS[:performance]
+
+      metrics = {
+        operation: operation,
+        duration_seconds: duration.round(3),
+        **additional_metrics
+      }
+
+      with_context(metrics) do
+        logger.info("Performance: #{operation} completed in #{duration.round(3)}s")
+      end
+    end
+
+    # Log a security event
+    #
+    # @param event [String] Description of the security event
+    # @param severity [Symbol] Severity level (:high, :medium, :low)
+    # @param details [Hash] Additional security-related details
+    def log_security(event, severity: :medium, details: {})
+      return unless logger.level <= CUSTOM_LEVELS[:security]
+
+      security_context = {
+        security_event: event,
+        severity: severity,
+        **details
+      }
+
+      with_context(security_context) do
+        logger.warn("SECURITY: #{event}")
+      end
+    end
+
+    # Log graph analysis information
+    #
+    # @param analysis_type [String] Type of analysis being performed
+    # @param graph_metrics [Hash] Metrics about the graph being analyzed
+    def log_graph_analysis(analysis_type, graph_metrics = {})
+      return unless logger.level <= CUSTOM_LEVELS[:graph_analysis]
+
+      analysis_context = {
+        analysis_type: analysis_type,
+        **graph_metrics
+      }
+
+      with_context(analysis_context) do
+        logger.debug("Graph Analysis: #{analysis_type}")
+        
+        if graph_metrics.any?
+          metrics_str = graph_metrics.map { |k, v| "#{k}=#{v}" }.join(', ')
+          logger.debug("Graph metrics: #{metrics_str}")
+        end
+      end
+    end
+
+    # Time a block and log its performance
+    #
+    # @param operation [String] Name of the operation being timed
+    # @param additional_metrics [Hash] Additional metrics to include
+    # @yield The block to time
+    # @return The result of the block
+    def time_operation(operation, additional_metrics = {})
+      start_time = Time.now
+      
+      begin
+        result = yield
+        duration = Time.now - start_time
+        log_performance(operation, duration, additional_metrics)
+        result
+      rescue => e
+        duration = Time.now - start_time
+        log_error(e, context: { 
+          operation: operation, 
+          duration_seconds: duration.round(3),
+          **additional_metrics 
+        })
+        raise
+      end
+    end
+
+    # Configure logging for different environments
+    #
+    # @param environment [Symbol] The environment (:development, :test, :production)
+    # @param options [Hash] Additional configuration options
+    def configure_for_environment(environment, options = {})
+      case environment
+      when :development
+        logger.level = Logger::DEBUG
+        logger.formatter = StructuredFormatter.new
+      when :test
+        logger.level = Logger::WARN
+        logger.formatter = Logger::Formatter.new
+      when :production
+        logger.level = Logger::INFO
+        logger.formatter = StructuredFormatter.new
+      end
+
+      # Apply any custom options
+      options.each do |key, value|
+        case key
+        when :level
+          logger.level = value
+        when :formatter
+          logger.formatter = value
+        end
+      end
+    end
+
+    private
+
+    def create_logger
+      logger = Logger.new(STDOUT)
+      logger.level = Logger::INFO
+      logger.formatter = StructuredFormatter.new
+      logger.progname = 'RailsFlowMap'
+      logger
+    end
+  end
+end

data/lib/rails_flow_map/models/flow_edge.rb

@@ -0,0 +1,31 @@
+module RailsFlowMap
+  class FlowEdge
+    attr_accessor :from, :to, :type, :label, :attributes
+
+    def initialize(from:, to:, type:, label: nil, attributes: {})
+      @from = from
+      @to = to
+      @type = type
+      @label = label
+      @attributes = attributes
+    end
+
+    def association?
+      [:belongs_to, :has_one, :has_many, :has_and_belongs_to_many].include?(type)
+    end
+
+    def action_flow?
+      type == :action_flow
+    end
+
+    def to_h
+      {
+        from: from,
+        to: to,
+        type: type,
+        label: label,
+        attributes: attributes
+      }
+    end
+  end
+end

data/lib/rails_flow_map/models/flow_graph.rb

@@ -0,0 +1,58 @@
+module RailsFlowMap
+  class FlowGraph
+    attr_reader :nodes, :edges
+
+    def initialize
+      @nodes = {}
+      @edges = []
+    end
+
+    def add_node(node)
+      @nodes[node.id] = node
+    end
+
+    def add_edge(edge)
+      @edges << edge
+    end
+
+    def find_node(id)
+      @nodes[id]
+    end
+
+    def nodes_by_type(type)
+      @nodes.values.select { |node| node.type == type }
+    end
+
+    def edges_by_type(type)
+      @edges.select { |edge| edge.type == type }
+    end
+
+    def connected_nodes(node_id, direction: :both)
+      case direction
+      when :outgoing
+        @edges.select { |e| e.from == node_id }.map { |e| @nodes[e.to] }.compact
+      when :incoming
+        @edges.select { |e| e.to == node_id }.map { |e| @nodes[e.from] }.compact
+      when :both
+        outgoing = @edges.select { |e| e.from == node_id }.map { |e| @nodes[e.to] }
+        incoming = @edges.select { |e| e.to == node_id }.map { |e| @nodes[e.from] }
+        (outgoing + incoming).compact.uniq
+      end
+    end
+
+    def node_count
+      @nodes.size
+    end
+
+    def edge_count
+      @edges.size
+    end
+
+    def to_h
+      {
+        nodes: @nodes.transform_values(&:to_h),
+        edges: @edges.map(&:to_h)
+      }
+    end
+  end
+end

data/lib/rails_flow_map/models/flow_node.rb

@@ -0,0 +1,37 @@
+module RailsFlowMap
+  class FlowNode
+    attr_accessor :id, :name, :type, :attributes, :file_path, :line_number
+
+    def initialize(id:, name:, type:, attributes: {}, file_path: nil, line_number: nil)
+      @id = id
+      @name = name
+      @type = type
+      @attributes = attributes
+      @file_path = file_path
+      @line_number = line_number
+    end
+
+    def model?
+      type == :model
+    end
+
+    def controller?
+      type == :controller
+    end
+
+    def action?
+      type == :action
+    end
+
+    def to_h
+      {
+        id: id,
+        name: name,
+        type: type,
+        attributes: attributes,
+        file_path: file_path,
+        line_number: line_number
+      }
+    end
+  end
+end

data/lib/rails_flow_map/version.rb

@@ -0,0 +1,3 @@
+module RailsFlowMap
+  VERSION = "0.1.0"
+end