trace_viz 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8fffeaf37d8c9d9854f95159dba5ab2c8d9657a4ad63828e04164a79911ba4a3
-  data.tar.gz: 8c868e5bd2e954611c280fcb23a68cbf059f8314a98f7aaba2d3da909197e203
+  metadata.gz: bb4571e8a37548c6819b56d576ec740c9052efe64c2984cd65a6a06f53e935b3
+  data.tar.gz: 7dfd025e87f5076957783b45512a6c8aca8b65dd98ec67bd6318681efd5d1d3c
 SHA512:
-  metadata.gz: 25fa2eb78c78ad670bc3dd5e2819880154e4119c7260ab4127d35d7f75bcf56a23e237a0eb4cbbd893e2d3f6547a57496b432a214a2145770bdb252385d7dd94
-  data.tar.gz: f267c37003eaa0a4a4427e6faedac0e83827e3e5c6433bc22aee68a32b5b14a07abc51cf6d71bbfaf9aff3bfb0448cd381d1e168bb34e345d95c138478623635
+  metadata.gz: 2bf8264a62463c20f1e585fac19835f8d739fe703c4dfaef159e8c3fde331ace651f750c17591da5c3441faf6cf33d9baff2af6048c457bdc89d3a5e76148015
+  data.tar.gz: 4ae53f49154cbb6b6c0a95075c62ccd698ad3154abb3a5871a2697019020a99634fa9a82ddee118d81ec29543de2ad5cd7610a6f57c6429d7700372581f2f91a

data/README.md

@@ -9,8 +9,6 @@
 
 TraceViz is a Ruby library designed to trace and visualize events executed in a block of code. It is useful for logging, debugging, and generating diagrams to understand code execution and flow.
 
-> **Note:** The diagram generation feature is currently under development.
-
 The gem allows you to customize how much detail you want to see, such as method calls, parameters, return values, and execution times.
 
 ## Demo
@@ -143,12 +141,14 @@ TraceViz.trace(
   },
   filters: [
     :exclude_internal_call,
-    include_classes: [Example]
+    include_classes: {
+      classes: [Example]
+    }
   ],
   export: {
     enabled: true,
     path: "tmp",
-    format: :txt,
+    format: :txt, # Select :mermaid to export a mermaid diagram
     overwrite: false,
   }
 ) do
@@ -159,8 +159,6 @@ end
 
 </details>
 
-**Output**
-
 <details open>
   <summary>Sample Output</summary>
 
@@ -178,45 +176,69 @@ Final result: 24
 
 </details>
 
+<details open>
+<summary>Sample Diagram</summary>
+
+```mermaid
+sequenceDiagram
+    box rgb(224, 236, 221) Example
+    participant E as Example
+    end
+    E ->> E: perform_task(x: 5, y: 7)
+    Note over E: 24
+    activate E
+    E ->> E: add_numbers(a: 5, b: 7)
+    Note over E: 24
+    activate E
+    E ->> E: multiply_by_factor(value: 12, factor: 2)
+    Note over E: 24
+    deactivate E
+    E ->> E: log_result(result: 24)
+    Note over E: nil
+    deactivate E
+```
+
+</details>
+
 ### Configuration Options
 
 TraceViz provides extensive configuration options to customize tracing behavior.
 
-| Group             | Option                     | Type             | Default Value               | Description                                                                |
-| ----------------- | -------------------------- | ---------------- | --------------------------- | -------------------------------------------------------------------------- |
-| `general`         | `tab_size`                 | Integer          | 2                           | Number of spaces for indentation.                                          |
-|                   | `mode`                     | Symbol           | `:summary`                  | Display mode (`:summary` or `:verbose`).                                   |
-|                   | `group_keys`               | Array of Symbols | `[:event, :klass, :action]` | Keys to group similar outputs.                                             |
-|                   | `show_indent`              | Boolean          | true                        | Enables visual indentation for nested calls.                               |
-|                   | `show_depth`               | Boolean          | true                        | Displays the depth level of the method call.                               |
-|                   | `max_display_depth`        | Integer          | 3                           | Maximum depth of calls to display.                                         |
-|                   | `show_method_name`         | Boolean          | true                        | Logs the name of the method being executed.                                |
-| `source_location` | `show`                     | Boolean          | false                       | Logs the source file and line number for methods.                          |
-|                   | `truncate_length`          | Integer          | 100                         | Maximum length of displayed source location information.                   |
-| `params`          | `show`                     | Boolean          | true                        | Logs method parameters.                                                    |
-|                   | `mode`                     | Symbol           | `:name_and_value`           | Parameter display mode (`:name`, `:value`, or `:name_and_value`).          |
-|                   | `truncate_values`          | Integer          | 50                          | Maximum length of parameter values to display.                             |
-| `result`          | `show`                     | Boolean          | true                        | Logs method return values.                                                 |
-|                   | `truncate_length`          | Integer          | 50                          | Maximum length of return value logs.                                       |
-| `execution`       | `show_time`                | Boolean          | true                        | Logs execution time for methods.                                           |
-|                   | `show_trace_events`        | Array of Symbols | `[:call, :return]`          | Specifies the trace events to log (e.g., `:call`, `:return`).              |
-| `filters`         | `:exclude_internal_call`   | Symbol           | N/A                         | Exclude internal Ruby calls.                                               |
-|                   | `:exclude_default_classes` | Symbol           | N/A                         | Skip logging standard library classes.                                     |
-|                   | `:exclude_rails_framework` | Symbol           | N/A                         | Ignore Rails framework classes and methods.                                |
-|                   | `include_classes`          | Hash             | N/A                         | Specify classes to include in tracing.                                     |
-|                   | - `classes`                | Array            | []                          | List of class names to include (e.g., `["ClassName"]`).                    |
-|                   | `exclude_classes`          | Hash             | N/A                         | Specify classes to exclude from tracing.                                   |
-|                   | - `classes`                | Array            | []                          | List of class names to exclude (e.g., `["ClassName"]`).                    |
-|                   | `include_gems`             | Hash             | N/A                         | Include specific gems or runtime application gems.                         |
-|                   | - `app_running`            | Boolean          | true                        | Include the code of the application.                                       |
-|                   | - `app_path`               | String           | `Dir.pwd`                   | Path to the application (e.g., `Dir.pwd`).                                 |
-|                   | - `gems`                   | Array            | []                          | List of gems to include (e.g., `["gem1", "gem2"]`).                        |
-|                   | `exclude_gems`             | Hash             | N/A                         | Exclude specified gems.                                                    |
-|                   | - `gems`                   | Array            | []                          | List of gems to exclude (e.g., `["excluded_gem"]`).                        |
-| `export`          | `enabled`                  | Boolean          | true                        | Enables or disables exporting of trace logs.                               |
-|                   | `path`                     | String           | `"tmp"`                     | Directory for exported trace logs.                                         |
-|                   | `format`                   | Symbol           | `:txt`                      | Format for trace logs (`:txt`). `.json` and `.yaml` are under development. |
-|                   | `overwrite`                | Boolean          | false                       | Prevents overwriting of existing exported files.                           |
+| Group             | Option                     | Type             | Default Value               | Description                                                                      |
+| ----------------- | -------------------------- | ---------------- | --------------------------- | -------------------------------------------------------------------------------- |
+| `general`         | `tab_size`                 | Integer          | 2                           | Number of spaces for indentation.                                                |
+|                   | `mode`                     | Symbol           | `:summary`                  | Display mode (`:summary` or `:verbose`).                                         |
+|                   | `group_keys`               | Array of Symbols | `[:event, :klass, :action]` | Keys to group similar outputs.                                                   |
+|                   | `show_indent`              | Boolean          | true                        | Enables visual indentation for nested calls.                                     |
+|                   | `show_depth`               | Boolean          | true                        | Displays the depth level of the method call.                                     |
+|                   | `max_display_depth`        | Integer          | 3                           | Maximum depth of calls to display.                                               |
+|                   | `show_method_name`         | Boolean          | true                        | Logs the name of the method being executed.                                      |
+| `source_location` | `show`                     | Boolean          | false                       | Logs the source file and line number for methods.                                |
+|                   | `truncate_length`          | Integer          | 100                         | Maximum length of displayed source location information.                         |
+| `params`          | `show`                     | Boolean          | true                        | Logs method parameters.                                                          |
+|                   | `mode`                     | Symbol           | `:name_and_value`           | Parameter display mode (`:name`, `:value`, or `:name_and_value`).                |
+|                   | `truncate_values`          | Integer          | 50                          | Maximum length of parameter values to display.                                   |
+| `result`          | `show`                     | Boolean          | true                        | Logs method return values.                                                       |
+|                   | `truncate_length`          | Integer          | 50                          | Maximum length of return value logs.                                             |
+| `execution`       | `show_time`                | Boolean          | true                        | Logs execution time for methods.                                                 |
+|                   | `show_trace_events`        | Array of Symbols | `[:call, :return]`          | Specifies the trace events to log (e.g., `:call`, `:return`).                    |
+| `filters`         | `:exclude_internal_call`   | Symbol           | N/A                         | Exclude internal Ruby calls.                                                     |
+|                   | `:exclude_default_classes` | Symbol           | N/A                         | Skip logging standard library classes.                                           |
+|                   | `:exclude_rails_framework` | Symbol           | N/A                         | Ignore Rails framework classes and methods.                                      |
+|                   | `include_classes`          | Hash             | N/A                         | Specify classes to include in tracing.                                           |
+|                   | - `classes`                | Array            | []                          | List of class names to include (e.g., `["ClassName"]`).                          |
+|                   | `exclude_classes`          | Hash             | N/A                         | Specify classes to exclude from tracing.                                         |
+|                   | - `classes`                | Array            | []                          | List of class names to exclude (e.g., `["ClassName"]`).                          |
+|                   | `include_gems`             | Hash             | N/A                         | Include specific gems or runtime application gems.                               |
+|                   | - `app_running`            | Boolean          | true                        | Include the code of the application.                                             |
+|                   | - `app_path`               | String           | `Dir.pwd`                   | Path to the application (e.g., `Dir.pwd`).                                       |
+|                   | - `gems`                   | Array            | []                          | List of gems to include (e.g., `["gem1", "gem2"]`).                              |
+|                   | `exclude_gems`             | Hash             | N/A                         | Exclude specified gems.                                                          |
+|                   | - `gems`                   | Array            | []                          | List of gems to exclude (e.g., `["excluded_gem"]`).                              |
+| `export`          | `enabled`                  | Boolean          | true                        | Enables or disables exporting of trace logs.                                     |
+|                   | `path`                     | String           | `"tmp"`                     | Directory for exported trace logs.                                               |
+|                   | `format`                   | Symbol           | `:txt`                      | Format for trace logs. Use :txt for plain text or :mermaid for mermaid diagrams. |
+|                   | `overwrite`                | Boolean          | false                       | Prevents overwriting of existing exported files.                                 |
 
 ### Notes
 

data/lib/trace_viz/builders/base_builder.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module TraceViz
+  module Builders
+    class BaseBuilder
+      def build
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/trace_viz/builders/diagram/base_builder.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module TraceViz
+  module Builders
+    module Diagram
+      class BaseBuilder
+      end
+    end
+  end
+end

data/lib/trace_viz/builders/diagram/message_builder.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "trace_viz/managers/diagram/participant_manager"
+require "trace_viz/models"
+require_relative "base_builder"
+
+module TraceViz
+  module Builders
+    module Diagram
+      class MessageBuilder < BaseBuilder
+        def initialize(formatter, participants)
+          super()
+          @formatter = formatter
+          @participants_manager = Managers::Diagram::ParticipantsManager.new(participants)
+        end
+
+        def build_call_message(from_trace, to_trace)
+          return if same_class?(from_trace, to_trace)
+
+          build(
+            :call,
+            from: participant_for(from_trace),
+            to: participant_for(to_trace),
+            content: formatter.format_call,
+          )
+        end
+
+        def build_return_message(from_trace, to_trace)
+          return if same_class?(from_trace, to_trace)
+
+          build(
+            :return,
+            from: participant_for(from_trace),
+            to: participant_for(to_trace),
+            content: formatter.format_return,
+          )
+        end
+
+        def build_loop_start_message(trace)
+          build(:loop_start, content: "#{trace.count} calls")
+        end
+
+        def build_loop_end_message
+          build(:loop_end)
+        end
+
+        def build_activate_message(trace)
+          build(:activate, to: participant_for(trace))
+        end
+
+        def build_deactivate_message(trace)
+          build(:deactivate, to: participant_for(trace))
+        end
+
+        def build_internal_message(trace)
+          build(
+            :call,
+            from: participant_for(trace),
+            to: participant_for(trace),
+            content: formatter.format_internal_message(trace),
+          )
+        end
+
+        def build_note(trace)
+          build(
+            :note,
+            from: participant_for(trace),
+            to: participant_for(trace),
+            content: formatter.format_result(trace),
+          )
+        end
+
+        private
+
+        attr_reader :formatter, :participants_manager
+
+        def build(type, from: nil, to: nil, content: "")
+          Models::Message.new(
+            type: type,
+            from: from,
+            to: to,
+            content: content,
+          )
+        end
+
+        def same_class?(from_trace, to_trace)
+          from_trace.klass == to_trace.klass
+        end
+
+        def participant_for(trace)
+          participants_manager.find(trace.klass)
+        end
+      end
+    end
+  end
+end

data/lib/trace_viz/builders/diagram/sequence_builder.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "trace_viz/models/diagram"
+require "trace_viz/extractors/diagram/box_extractor"
+require "trace_viz/extractors/diagram/message_extractor"
+require_relative "base_builder"
+
+module TraceViz
+  module Builders
+    module Diagram
+      class SequenceBuilder < BaseBuilder
+        def initialize(collector)
+          super()
+          @collector = collector
+        end
+
+        def build
+          Models::Diagram.new.tap do |diagram|
+            add_boxes_to(diagram)
+            add_messages_to(diagram)
+          end
+        end
+
+        private
+
+        attr_reader :collector
+
+        def add_boxes_to(diagram)
+          boxes.each { |box| diagram.add_box(box) }
+        end
+
+        def add_messages_to(diagram)
+          messages.each { |message| diagram.add_message(message) }
+        end
+
+        def boxes
+          @boxes ||= Extractors::Diagram::BoxExtractor.new(collector).extract
+        end
+
+        def participants
+          @participants ||= boxes.flat_map(&:participants)
+        end
+
+        def messages
+          @messages ||= Extractors::Diagram::MessageExtractor.new(collector, participants).extract
+        end
+      end
+    end
+  end
+end

data/lib/trace_viz/collectors/filters/base_class_filter.rb

@@ -17,7 +17,9 @@ module TraceViz
 
         def normalize_class_name(klass)
           # Normalize class/module names to handle dynamic/nested representations
-          klass.to_s.gsub(/^#<Class:/, "").gsub(/>$/, "").strip
+          klass.to_s
+            .gsub(/^#<Class/, "<Class")
+            .strip
         end
 
         def matches_hierarchy?(klass_name, target_name)

data/lib/trace_viz/config/validator.rb

@@ -38,7 +38,7 @@ module TraceViz
       end
 
       def validate_result(value)
-        if value[:truncate_length] && !value[:truncate_length].is_a?(Integer)
+        if value[:truncate_value] && !value[:truncate_value].is_a?(Integer)
           raise ArgumentError, "Truncate values must be a positive integer."
         end
       end

data/lib/trace_viz/defaults/config.rb

@@ -21,10 +21,12 @@ module TraceViz
           show: true,
           mode: :name_and_value,
           truncate_values: 10,
+          truncate_length: -1,
         },
         result: {
           show: true,
-          truncate_length: 50,
+          truncate_value: 50,
+          truncate_length: 30,
         },
         execution: {
           show_time: true,
@@ -77,7 +79,7 @@ module TraceViz
         end
 
         def valid_export_formats
-          [:txt, :json, :yaml].freeze
+          [:txt, :json, :yaml, :mermaid].freeze
         end
 
         def valid_export_format?(format)

data/lib/trace_viz/exporters/base_exporter.rb

@@ -3,6 +3,8 @@
 require "fileutils"
 require "trace_viz/helpers"
 require "trace_viz/shared"
+require "trace_viz/renderers/renderer_builder"
+require "trace_viz/formatters/export/formatter_factory"
 
 module TraceViz
   module Exporters
@@ -15,6 +17,12 @@ module TraceViz
         @logger = config.logger
 
         @collector = collector
+
+        @renderer = Renderers::RendererBuilder.build(
+          collector,
+          key: renderer_mode,
+          formatter_factory: Formatters::Export::FormatterFactory.new,
+        )
       end
 
       def export
@@ -34,10 +42,18 @@ module TraceViz
 
       private
 
-      attr_reader :export_config, :logger, :collector
+      attr_reader :export_config, :logger, :collector, :renderer
+
+      def renderer_mode
+        fetch_general_config(:mode)
+      end
 
       def content
-        raise NotImplementedError
+        data.join("\n")
+      end
+
+      def data
+        process_lines(renderer.to_lines) { |line| line[:line] }
       end
 
       def export_enabled?
@@ -67,10 +83,15 @@ module TraceViz
       end
 
       def file_path
-        format = export_config[:format]
-        path = export_config[:path]
+        "#{export_directory}/trace_output#{file_extension}"
+      end
 
-        "#{path}/trace_output.#{format}"
+      def export_directory
+        export_config[:path]
+      end
+
+      def file_extension
+        raise NotImplementedError
       end
 
       def write_file(data)

data/lib/trace_viz/exporters/mermaid_exporter.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module TraceViz
+  module Exporters
+    class MermaidExporter < BaseExporter
+      private
+
+      def renderer_mode
+        :sequence_diagram
+      end
+
+      def file_extension
+        ".mmd"
+      end
+    end
+  end
+end

data/lib/trace_viz/exporters/registry.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 require_relative "text_exporter"
+require_relative "mermaid_exporter"
 
 module TraceViz
   module Exporters
     class Registry
       EXPORTS = {
         txt: TextExporter,
+        mermaid: MermaidExporter,
       }
 
       class << self

data/lib/trace_viz/exporters/text_exporter.rb

@@ -1,36 +1,14 @@
 # frozen_string_literal: true
 
 require_relative "base_exporter"
-require "trace_viz/renderers/renderer_factory"
-require "trace_viz/renderers/render_context"
-require "trace_viz/formatters/export/formatter_factory"
 
 module TraceViz
   module Exporters
     class TextExporter < BaseExporter
-      def initialize(collector)
-        super(collector)
-
-        @renderer = build_renderer(collector, Formatters::Export::FormatterFactory)
-      end
-
       private
 
-      attr_reader :renderer
-
-      def content
-        data.join("\n")
-      end
-
-      def data
-        process_lines(renderer.to_lines) { |line| process_line(line) }
-      end
-
-      def process_line(line)
-        [
-          line[:line],
-          *process_lines(line[:nested_lines]) { |nested| process_line(nested) },
-        ].compact
+      def file_extension
+        ".txt"
       end
     end
   end

data/lib/trace_viz/extractors/base_extractor.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module TraceViz
+  module Extractors
+    class BaseExtractor
+      attr_reader :collector
+
+      def initialize(collector)
+        @collector = collector
+      end
+
+      def extract
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/trace_viz/extractors/diagram/base_extractor.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "trace_viz/transformers/summary_transformer"
+require_relative "../base_extractor"
+
+module TraceViz
+  module Extractors
+    module Diagram
+      class BaseExtractor < BaseExtractor
+        private
+
+        def data
+          @data ||= Transformers::SummaryTransformer.new(collector).transform
+        end
+      end
+    end
+  end
+end

data/lib/trace_viz/extractors/diagram/box_extractor.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "base_extractor"
+require_relative "participant_extractor"
+require "trace_viz/models/box"
+
+module TraceViz
+  module Extractors
+    module Diagram
+      class BoxExtractor < BaseExtractor
+        def initialize(collector)
+          super(collector)
+
+          @participants = ParticipantExtractor.new(collector).extract
+        end
+
+        def extract
+          grouped_participants = group_by_namespace(@participants)
+
+          grouped_participants.map do |namespace, participants|
+            box = Models::Box.new(
+              color: random_rgb,
+              description: namespace,
+            )
+
+            participants.each do |participant|
+              box.add_participant(participant)
+            end
+
+            box
+          end
+        end
+
+        private
+
+        def group_by_namespace(participants)
+          participants.group_by { |participant| extract_namespace(participant.name) }
+        end
+
+        def extract_namespace(klass_name)
+          klass_name.split("::").first
+        end
+
+        def random_rgb
+          "rgb(#{rand(200..255)}, #{rand(200..255)}, #{rand(200..255)})"
+        end
+      end
+    end
+  end
+end

data/lib/trace_viz/extractors/diagram/message_extractor.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "processors/message_processor"
+require_relative "base_extractor"
+
+module TraceViz
+  module Extractors
+    module Diagram
+      class MessageExtractor < BaseExtractor
+        def initialize(collector, participants)
+          super(collector)
+
+          @node_processor = Processors::MessageProcessor.new(participants)
+        end
+
+        def extract
+          root = data
+          root.children.flat_map { |child| @node_processor.process_node(child) }
+        end
+      end
+    end
+  end
+end

data/lib/trace_viz/extractors/diagram/participant_extractor.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "trace_viz/utils/alias_generator"
+require "trace_viz/models/participant"
+require_relative "base_extractor"
+
+module TraceViz
+  module Extractors
+    module Diagram
+      class ParticipantExtractor < BaseExtractor
+        def extract
+          unique_names = data.map(&:klass).uniq
+
+          assigned_aliases = {}
+
+          unique_names.map do |raw_name|
+            alias_name = Utils::AliasGenerator.generate(
+              name: raw_name,
+              assigned_aliases: assigned_aliases,
+            )
+
+            Models::Participant.new(
+              name: raw_name.to_s,
+              alias_name: alias_name,
+            )
+          end
+        end
+
+        private
+
+        def data
+          collector.collection
+        end
+      end
+    end
+  end
+end