Module: RailsFlowMap

Defined in:
lib/rails_flow_map.rb,
lib/rails_flow_map/engine.rb,
lib/rails_flow_map/errors.rb,
lib/rails_flow_map/logging.rb,
lib/rails_flow_map/version.rb,
lib/rails_flow_map/configuration.rb,
lib/rails_flow_map/models/flow_edge.rb,
lib/rails_flow_map/models/flow_node.rb,
lib/rails_flow_map/models/flow_graph.rb,
lib/rails_flow_map/analyzers/model_analyzer.rb,
lib/rails_flow_map/formatters/erd_formatter.rb,
lib/rails_flow_map/formatters/d3js_formatter.rb,
lib/rails_flow_map/formatters/mermaid_formatter.rb,
lib/rails_flow_map/formatters/metrics_formatter.rb,
lib/rails_flow_map/formatters/openapi_formatter.rb,
lib/rails_flow_map/generators/install_generator.rb,
lib/rails_flow_map/analyzers/controller_analyzer.rb,
lib/rails_flow_map/formatters/git_diff_formatter.rb,
lib/rails_flow_map/formatters/graphviz_formatter.rb,
lib/rails_flow_map/formatters/plantuml_formatter.rb,
lib/rails_flow_map/formatters/sequence_formatter.rb

Overview

RailsFlowMap is a comprehensive tool for visualizing data flows in Rails applications

It analyzes your Rails application’s structure and generates various visualization formats to help understand the architecture, dependencies, and data flow patterns.

Examples:

Basic usage

# Analyze the entire application
graph = RailsFlowMap.analyze

# Export to different formats
RailsFlowMap.export(graph, format: :mermaid, output: 'architecture.md')
RailsFlowMap.export(graph, format: :d3js, output: 'interactive.html')

Analyzing specific endpoints

graph = RailsFlowMap.analyze_endpoint('/api/v1/users')
RailsFlowMap.export(graph, format: :sequence, endpoint: '/api/v1/users')

Comparing versions

before = RailsFlowMap.analyze_at('v1.0.0')
after = RailsFlowMap.analyze
diff = RailsFlowMap.diff(before, after)

Defined Under Namespace

Modules: ErrorHandler, Formatters, Generators, Logging Classes: Configuration, ConfigurationError, ControllerAnalyzer, D3jsFormatter, Engine, ErdFormatter, Error, FileOperationError, FlowEdge, FlowGraph, FlowNode, FormatterError, GitDiffFormatter, GraphParseError, GraphValidationError, GraphVizFormatter, InvalidInputError, MermaidFormatter, MetricsFormatter, ModelAnalyzer, NotImplementedError, OpenapiFormatter, PlantUMLFormatter, ResourceLimitError, SecurityError, SequenceFormatter

Constant Summary collapse

VERSION = 
"0.1.0"

Class Method Summary collapse

Class Method Details

.analyze(options = {}) ⇒ FlowGraph

Analyzes the Rails application and builds a flow graph

Parameters:

  • options (Hash) (defaults to: {}) —

    Analysis options

Options Hash (options):

  • :models (Boolean) —

    Include model analysis (default: true)

  • :controllers (Boolean) —

    Include controller analysis (default: true)

  • :routes (Boolean) —

    Include route analysis (default: true)

  • :services (Boolean) —

    Include service analysis (default: true)

Returns:

  • (FlowGraph) —

    The analyzed application graph

Raises:



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/rails_flow_map.rb', line 82

def analyze(options = {})
  ErrorHandler.with_error_handling("analyze", context: { options: options }) do
    Logging.time_operation("graph_analysis", { analyzers: options.keys }) do
      graph = FlowGraph.new
      
      analyzers_run = []
      
      if options[:models] != false
        analyzers_run << "models"
        ModelAnalyzer.new(graph).analyze
      end
      
      if options[:controllers] != false
        analyzers_run << "controllers"
        ControllerAnalyzer.new(graph).analyze
      end
      
      Logging.log_graph_analysis("completed", {
        nodes: graph.nodes.size,
        edges: graph.edges.size,
        analyzers: analyzers_run.join(", ")
      })
      
      graph
    end
  end
end

.analyze_at(ref) ⇒ FlowGraph

Note:

This is currently a placeholder implementation that returns the current state. A full implementation would require Git integration to checkout the ref, analyze, and return to the original state.

Analyzes the application at a specific Git reference

Examples:

graph = RailsFlowMap.analyze_at('v1.0.0')
graph = RailsFlowMap.analyze_at('main')
graph = RailsFlowMap.analyze_at('abc123f')

Parameters:

  • ref (String) —

    The Git reference (branch, tag, or commit SHA)

Returns:

  • (FlowGraph) —

    The analyzed graph at the specified reference



183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/rails_flow_map.rb', line 183

def analyze_at(ref)
  # Note: This is a placeholder implementation
  # In a real implementation, you would:
  # 1. Save current changes
  # 2. Checkout the specified ref
  # 3. Run analysis
  # 4. Return to original state
  # 
  # For now, returns current state
  analyze
end

.configuration ⇒ Object 



56
57
58
 
# File 'lib/rails_flow_map.rb', line 56

def configuration
  @configuration ||= Configuration.new
end

.configure {|Configuration| ... } ⇒ Object

Configures RailsFlowMap

Examples:

RailsFlowMap.configure do |config|
  config.include_models = true
  config.include_controllers = true
  config.output_dir = 'doc/flow_maps'
end

Yields:



69
70
71
 
# File 'lib/rails_flow_map.rb', line 69

def configure
  yield(configuration)
end

.diff(before_graph, after_graph, format: :mermaid, **options) ⇒ String

Compares two graphs and generates a diff visualization

Examples:

before = RailsFlowMap.analyze_at('main')
after = RailsFlowMap.analyze
diff = RailsFlowMap.diff(before, after, format: :mermaid)

Parameters:

  • before_graph (FlowGraph) —

    The “before” state graph

  • after_graph (FlowGraph) —

    The “after” state graph

  • format (Symbol) (defaults to: :mermaid) —

    The output format (:mermaid, :html, :text)

  • options (Hash) —

    Additional options for the formatter

Returns:

  • (String) —

    The formatted diff



167
168
169
170
 
# File 'lib/rails_flow_map.rb', line 167

def diff(before_graph, after_graph, format: :mermaid, **options)
  formatter = GitDiffFormatter.new(before_graph, after_graph, options.merge(format: format))
  formatter.format
end

.export(graph, format: :mermaid, output: nil, **options) ⇒ String

Exports a flow graph to various visualization formats

Examples:

Export to Mermaid

RailsFlowMap.export(graph, format: :mermaid, output: 'flow.md')

Export to interactive HTML

RailsFlowMap.export(graph, format: :d3js, output: 'interactive.html')

Parameters:

  • graph (FlowGraph) —

    The graph to export

  • format (Symbol) (defaults to: :mermaid) —

    The output format (:mermaid, :plantuml, :graphviz, :erd, :metrics, :d3js, :openapi, :sequence)

  • output (String, nil) (defaults to: nil) —

    The output file path (returns string if nil)

  • options (Hash) —

    Format-specific options

Returns:

  • (String) —

    The formatted output

Raises:



125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/rails_flow_map.rb', line 125

def export(graph, format: :mermaid, output: nil, **options)
  ErrorHandler.with_error_handling("export", context: { format: format, output: output }) do
    # Input validation
    ErrorHandler.validate_input!({
      graph: -> { graph.is_a?(FlowGraph) || graph.nil? },
      format: -> { format.is_a?(Symbol) },
      output: -> { output.nil? || output.is_a?(String) }
    }, context: { operation: "export" })

    # Security validation for output path
    if output
      validate_output_path!(output)
    end

    Logging.time_operation("export", { format: format, nodes: graph&.nodes&.size || 0 }) do
      formatter = create_formatter(format, graph, options)
      
      Logging.with_context(formatter: formatter.class.name) do
        result = formatter.format(graph)
        
        if output
          write_output_file(output, result)
          Logging.logger.info("Successfully exported to #{output}")
        end
        
        result
      end
    end
  end
end