trailblazer-developer 0.0.26 → 0.0.28

data/lib/trailblazer/developer/trace.rb

@@ -1,16 +1,12 @@
-require 'trailblazer/activity'
-
 module Trailblazer::Developer
   module Trace
 
-    Activity = Trailblazer::Activity
-
     class << self
       # Public entry point to activate tracing when running {activity}.
       def call(activity, (ctx, flow_options), **circuit_options)
         activity, (ctx, flow_options), circuit_options = Trace.arguments_for_call( activity, [ctx, flow_options], **circuit_options ) # only run once for the entire circuit!
 
-        signal, (ctx, flow_options) = Activity::TaskWrap.invoke(activity, [ctx, flow_options], **circuit_options)
+        signal, (ctx, flow_options) = Trailblazer::Activity::TaskWrap.invoke(activity, [ctx, flow_options], **circuit_options)
 
         return flow_options[:stack], signal, [ctx, flow_options]
       end
@@ -19,21 +15,20 @@ module Trailblazer::Developer
 
       def arguments_for_call(activity, (options, original_flow_options), **original_circuit_options)
         default_flow_options = {
-          stack: Trace::Stack.new,
-
-          input_data_collector: Trace.method(:default_input_data_collector),
-          output_data_collector: Trace.method(:default_output_data_collector),
+          stack:                  Trace::Stack.new,
+          input_data_collector:   Trace.method(:default_input_data_collector),
+          output_data_collector:  Trace.method(:default_output_data_collector),
         }
 
-        flow_options = { **default_flow_options, **Hash( original_flow_options ) }
+        flow_options = {**default_flow_options, **Hash(original_flow_options)}
 
         default_circuit_options = {
-          wrap_runtime:  ::Hash.new(Trace.merge_plan), # DISCUSS: this overrides existing {:wrap_runtime}.
+          wrap_runtime:  ::Hash.new(Trace.task_wrap_extensions), # DISCUSS: this overrides existing {:wrap_runtime}.
         }
 
-        circuit_options = { **original_circuit_options, **default_circuit_options }
+        circuit_options = {**original_circuit_options, **default_circuit_options}
 
-        return activity, [ options, flow_options ], circuit_options
+        return activity, [options, flow_options], circuit_options
       end
     end
 
@@ -42,16 +37,10 @@ module Trailblazer::Developer
     # and before the TaskWrap is finished.
     #
     # @private
-    def merge_plan
-      Activity::TaskWrap::Extension.new(
-        {
-          insert: [Activity::Adds::Insert.method(:Prepend), "task_wrap.call_task"],
-          row:    Activity::TaskWrap::Pipeline.Row("task_wrap.capture_args", Trace.method(:capture_args))
-        },
-        {
-          insert: [Activity::Adds::Insert.method(:Append)], # append to the very end of tW.
-          row:    Activity::TaskWrap::Pipeline.Row("task_wrap.capture_return", Trace.method(:capture_return))
-        },
+    def task_wrap_extensions
+      Trailblazer::Activity::TaskWrap.Extension(
+        [Trace.method(:capture_args),   id: "task_wrap.capture_args",   prepend: "task_wrap.call_task"],
+        [Trace.method(:capture_return), id: "task_wrap.capture_return", append: nil], # append to the very end of tW.
       )
     end
 
@@ -60,112 +49,62 @@ module Trailblazer::Developer
     # us a better way.
     # taskWrap step to capture incoming arguments of a step.
     def capture_args(wrap_config, ((ctx, flow), circuit_options))
-      flow[:stack].indent!
+      original_args = [[ctx, flow], circuit_options]
 
-      flow[:stack] << Entity::Input.new(
-        wrap_config[:task],
-        circuit_options[:activity],
-        flow[:input_data_collector].call(wrap_config, [ctx, flow], circuit_options)
-      ).freeze
+      captured_input = Captured(Captured::Input, flow[:input_data_collector], wrap_config, original_args)
+
+      flow[:stack] << captured_input
 
-      return wrap_config, [[ctx, flow], circuit_options]
+      return wrap_config, original_args
     end
 
     # taskWrap step to capture outgoing arguments from a step.
     def capture_return(wrap_config, ((ctx, flow), circuit_options))
-      flow[:stack] << Entity::Output.new(
-        wrap_config[:task],
-        {},
-        flow[:output_data_collector].call(wrap_config, [ctx, flow], circuit_options)
-      ).freeze
+      original_args = [[ctx, flow], circuit_options]
 
-      flow[:stack].unindent!
+      captured_output = Captured(Captured::Output, flow[:output_data_collector], wrap_config, original_args)
 
-      return wrap_config, [[ctx, flow], circuit_options]
-    end
-
-    def default_input_data_collector(wrap_config, (ctx, _), circuit_options)
-      graph = Trailblazer::Activity::Introspect::Graph(circuit_options[:activity])
-      task  = wrap_config[:task]
-      name  = (node = graph.find { |node| node[:task] == task }) ? node[:id] : task
-
-      { ctx: ctx, task_name: name }
-    end
+      flow[:stack] << captured_output
 
-    def default_output_data_collector(wrap_config, (ctx, _), _)
-      { ctx: ctx, signal: wrap_config[:return_signal] }
+      return wrap_config, original_args
     end
 
-    # Structures used in {capture_args} and {capture_return}.
-    # These get pushed onto one {Level} in a {Stack}.
-    #
-    #   Level[
-    #     Level[              ==> this is a scalar task
-    #       Entity::Input
-    #       Entity::Output
-    #     ]
-    #     Level[              ==> nested task
-    #       Entity::Input
-    #       Level[
-    #         Entity::Input
-    #         Entity::Output
-    #       ]
-    #       Entity::Output
-    #     ]
-    #   ]
-    Entity         = Struct.new(:task, :activity, :data)
-    Entity::Input  = Class.new(Entity)
-    Entity::Output = Class.new(Entity)
-
-    class Level < Array
-      def inspect
-        %{<Level>#{super}}
-      end
-
-      # @param level {Trace::Level}
-      def self.input_output_nested_for_level(level)
-        input  = level[0]
-        output = level[-1]
-
-        output, nested = output.is_a?(Entity::Output) ? [output, level-[input, output]] : [nil, level[1..-1]]
+    def Captured(captured_class, data_collector, wrap_config, ((ctx, flow), circuit_options))
+      collected_data = data_collector.call(wrap_config, [[ctx, flow], circuit_options])
 
-        return input, output, nested
-      end
+      captured_class.new( # either Input or Output
+        wrap_config[:task],
+        circuit_options[:activity],
+        collected_data
+      ).freeze
     end
 
-    # Mutable/stateful per design. We want a (global) stack!
-    class Stack
-      attr_reader :top
-
-      def initialize
-        @nested  = Level.new
-        @stack   = [ @nested ]
-      end
-
-      def indent!
-        current << indented = Level.new
-        @stack << indented
-      end
-
-      def unindent!
-        @stack.pop
-      end
-
-      def <<(entity)
-        @top = entity
+    # Called in {#Captured}.
+    # DISCUSS: this is where to start for a new {Inspector} implementation.
+    def default_input_data_collector(wrap_config, ((ctx, _), _)) # DISCUSS: would it be faster to access ctx via {original_args[0][0]}?
+      # mutable, old_ctx = ctx.decompose
+      # mutable, old_ctx = ctx, nil
 
-        current << entity
-      end
+      {
+        # ctx: ctx.to_h.freeze,
+        ctx_snapshot: ctx.to_h.collect { |k,v| [k, v.inspect] }.to_h,
+      } # TODO: proper snapshot!
+    end
 
-      def to_a
-        @nested
-      end
+    # Called in {#Captured}.
+    def default_output_data_collector(wrap_config, ((ctx, _), _))
+      returned_ctx, _ = wrap_config[:return_args]
 
-      private
+      # FIXME: snapshot!
+      {
+        # ctx: ctx.to_h.freeze,
+        ctx_snapshot: returned_ctx.to_h.collect { |k,v| [k, v.inspect] }.to_h,
+        signal: wrap_config[:return_signal]
+      }
+    end
 
-      def current
-        @stack.last
-      end
-    end # Stack
+    Captured         = Struct.new(:task, :activity, :data)
+    Captured::Input  = Class.new(Captured)
+    Captured::Output = Class.new(Captured)
   end
 end

data/lib/trailblazer/developer/version.rb

@@ -1,7 +1,7 @@
 module Trailblazer
   module Version
     module Developer
-      VERSION = "0.0.26"
+      VERSION = "0.0.28"
     end
   end
 end

data/lib/trailblazer/developer/wtf/renderer.rb

@@ -1,4 +1,3 @@
-
 module Trailblazer::Developer
   module Wtf
 
@@ -15,24 +14,24 @@ module Trailblazer::Developer
 
       module_function
 
-      # tree: Array of Trace::TreeNodes::Node
-      # task_node - current Trace::TreeNodes::Node to render
-      # position - task_node's position in tree
-      def call(tree:, task_node:, position:)
-        value = value_for(tree, task_node, position)
-        [task_node.level, value]
+      # {options} can be {style: {#<Captured::Input> => [:red, :bold]}}
+      def call(tree:, debugger_node:, style: {}, **options)
+        label = styled_label(tree, debugger_node, style: style, **options)
+
+        [debugger_node.level, label]
       end
 
-      def value_for(tree, task_node, position)
-        if task_node.output.nil? && tree[position.next].nil? # i.e. when exception raised
-          return %{#{fmt(fmt(task_node.value, :red), :bold)}}
-        end
+      def styled_label(tree, debugger_node, color_map:, **options)
+        label = apply_style(debugger_node.label, debugger_node, **options)
 
-        if task_node.output.nil? # i.e. on entry/exit point of activity
-          return %{#{task_node.value}}
-        end
+        %{#{fmt(label, color_map[ signal_of(debugger_node) ])}}
+      end
+
+      def apply_style(label, debugger_node, style:, **)
+        return label unless styles = style[debugger_node.captured_input]
 
-        %{#{fmt(task_node.value, task_node.color_map[ signal_of(task_node) ])}}
+        styles.each { |s| label = fmt(label, s) }
+        label
       end
 
       def fmt(line, style)
@@ -44,7 +43,7 @@ module Trailblazer::Developer
       end
 
       def signal_of(task_node)
-        entity_signal = task_node.output.data[:signal]
+        entity_signal = task_node.captured_output.data[:signal]
         entity_klass = entity_signal.is_a?(Class) ? entity_signal : entity_signal.class
 
         SIGNALS_MAP[entity_klass.name.to_sym]

data/lib/trailblazer/developer/wtf.rb

@@ -14,77 +14,64 @@ module Trailblazer::Developer
 
     # Run {activity} with tracing enabled and inject a mutable {Stack} instance.
     # This allows to display the trace even when an exception happened
-    def invoke(activity, (ctx, flow_options), **circuit_options)
-      activity, (ctx, flow_options), circuit_options = Wtf.arguments_for_trace(
-        activity, [ctx, flow_options], **circuit_options
-      )
+    def invoke(activity, (ctx, flow_options), present_options: {}, **circuit_options)
+      flow_options ||= {}
 
-      _returned_stack, signal, (ctx, flow_options) = Trace.invoke(
-        activity, [ctx, flow_options], **circuit_options
-      )
+      stack = Trace::Stack.new # unfortunately, we need this mutable object before things break.
 
-      return signal, [ctx, flow_options], circuit_options
-    ensure
-      puts Trace::Present.(
-        flow_options[:stack],
-        renderer: Wtf::Renderer,
-        color_map: Wtf::Renderer::DEFAULT_COLOR_MAP.merge( flow_options[:color_map] || {} ),
+      complete_stack, signal, (ctx, flow_options) = Trace.invoke(
+        activity,
+        [ctx, flow_options.merge(stack: stack)],
+        **circuit_options
       )
-    end
-
-    def arguments_for_trace(activity, (ctx, original_flow_options), **circuit_options)
-      default_flow_options = {
-        # this instance gets mutated with every step. unfortunately, there is
-        # no other way in Ruby to keep the trace even when an exception was thrown.
-        stack: Trace::Stack.new,
-
-        input_data_collector: method(:trace_input_data_collector),
-        output_data_collector: method(:trace_output_data_collector),
-      }
 
-      # Merge default options with flow_options as an order of precedence
-      flow_options = { **default_flow_options, **Hash( original_flow_options ) }
-
-      # Normalize `focus_on` param to
-      #   1. Wrap step and variable names into an array if not already
-      flow_options[:focus_on] = {
-        steps: Array( flow_options.dig(:focus_on, :steps) ),
-        variables: Array( flow_options.dig(:focus_on, :variables) ),
-      }
+      return signal, [ctx, flow_options], circuit_options
 
-      [activity, [ ctx, flow_options ], circuit_options]
-    end
+    ensure
+      # incomplete_stack = flow_options[:stack]
+      incomplete_stack = stack
 
-    # Overring default input and output data collectors to collect/capture
-    #   1. inspect of focusable variables for given focusable step
-    #   2. Or inspect of focused variables for all steps
-    def trace_input_data_collector(wrap_config, (ctx, flow_options), circuit_options)
-      data = Trace.default_input_data_collector(wrap_config, [ctx, flow_options], circuit_options)
+        # in 99%, exception_source is a {Captured::Input}.
+      exception_source = incomplete_stack.to_a.last  # DISCUSS: in most cases, this is where the problem has happened.
+                                                #   However, what if an error happens in, say, an input filter? TODO: test this
 
-      if Wtf.capture_variables?(step_name: data[:task_name], **flow_options)
-        data[:focused_variables] = Trace::Focusable.capture_variables_from(ctx, **flow_options)
-      end
+      complete_stack = Exception::Stack.complete(incomplete_stack) # TODO: only in case of exception!
 
-      data
+      puts Trace::Present.(
+        complete_stack,
+        # we can hand in options per node, identified by their captured_input part.
+        node_options: {
+          exception_source => {data: {exception_source: true}}, # goes to {Debugger::Node.build}
+        },
+
+        renderer:   Wtf::Renderer,
+        color_map:  Wtf::Renderer::DEFAULT_COLOR_MAP.merge( flow_options[:color_map] || {} ),
+        style: {exception_source => [:red, :bold]},
+        **present_options, # TODO: test.
+      )
     end
 
-    def trace_output_data_collector(wrap_config, (ctx, flow_options), circuit_options)
-      data  = Trace.default_output_data_collector(wrap_config, [ctx, flow_options], circuit_options)
-      input = flow_options[:stack].top
+    module Exception
+      # When an exception occurs the Stack instance is incomplete - it is missing Captured::Output instances
+      # for Inputs still open. This method adds the missing elements so the Trace::Tree algorithm doesn't crash.
+      module Stack
+        def self.complete(incomplete_stack)
+          processed = []
 
-      if Wtf.capture_variables?(step_name: input.data[:task_name], **flow_options)
-        data[:focused_variables] = Trace::Focusable.capture_variables_from(ctx, **flow_options)
-      end
+          incomplete_stack.to_a.each do |captured|
+            if captured.is_a?(Trace::Captured::Input)
+              processed << captured
+            else
+              processed.pop
+            end
+          end
 
-      data
-    end
+          missing_captured = processed.reverse.collect { |captured| Trace::Captured::Output.new(captured.task, captured.activity, {}) }
 
-    # private
-    def capture_variables?(step_name:, focus_on:, **)
-      return true if focus_on[:steps].include?(step_name)                 # For given step
-      return true if focus_on[:steps].empty? && focus_on[:variables].any? # For selected vars but all steps
+          Trace::Stack.new(incomplete_stack.to_a + missing_captured)
+        end
+      end # Stack
 
-      false
     end
   end
 end

data/lib/trailblazer/developer.rb

@@ -6,11 +6,17 @@ module Trailblazer
   end
 end
 
+require "trailblazer/activity"
 require "trailblazer/developer/wtf"
 require "trailblazer/developer/wtf/renderer"
 require "trailblazer/developer/trace"
+require "trailblazer/developer/trace/stack"
+require "trailblazer/developer/trace/tree"
 require "trailblazer/developer/trace/present"
-require "trailblazer/developer/trace/focusable"
-require "trailblazer/developer/trace/inspector"
+require "trailblazer/developer/trace/debugger"
 require "trailblazer/developer/render/circuit"
 require "trailblazer/developer/render/linear"
+require "trailblazer/developer/render/task_wrap"
+require "trailblazer/developer/introspect" # TODO: might get removed, again.
+require "trailblazer/developer/trace/debugger/normalizer"
+require "trailblazer/developer/introspect/graph"

data/trailblazer-developer.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
 
   spec.summary       = "Developer tools for Trailblazer."
   spec.description   = "Developer tools for Trailblazer: debugger, activity visualizer and tracing."
-  spec.homepage      = "http://trailblazer.to"
+  spec.homepage      = "http://trailblazer.to/2.1/docs/trailblazer.html#trailblazer-developer"
   spec.license       = "LGPL-3.0"
 
   spec.files = `git ls-files -z`.split("\x0").reject do |f|
@@ -22,7 +22,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "minitest"
   spec.add_development_dependency "minitest-line"
   spec.add_development_dependency "rake"
+  spec.add_development_dependency "trailblazer-operation", ">= 0.10.0"
 
-  spec.add_dependency "trailblazer-activity-dsl-linear", ">= 1.0.0.beta1", "< 1.1.0"
+  spec.add_dependency "trailblazer-activity-dsl-linear", ">= 1.2.0", "< 1.3.0"
   spec.add_dependency "hirb"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trailblazer-developer
 version: !ruby/object:Gem::Version
-  version: 0.0.26
+  version: 0.0.28
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-07-19 00:00:00.000000000 Z
+date: 2023-03-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -66,26 +66,40 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: trailblazer-operation
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.10.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.10.0
 - !ruby/object:Gem::Dependency
   name: trailblazer-activity-dsl-linear
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.0.beta1
+        version: 1.2.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: 1.1.0
+        version: 1.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.0.beta1
+        version: 1.2.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: 1.1.0
+        version: 1.3.0
 - !ruby/object:Gem::Dependency
   name: hirb
   requirement: !ruby/object:Gem::Requirement
@@ -116,19 +130,23 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
-- gems.local.rb
 - lib/trailblazer/developer.rb
+- lib/trailblazer/developer/introspect.rb
+- lib/trailblazer/developer/introspect/graph.rb
 - lib/trailblazer/developer/render/circuit.rb
 - lib/trailblazer/developer/render/linear.rb
+- lib/trailblazer/developer/render/task_wrap.rb
 - lib/trailblazer/developer/trace.rb
-- lib/trailblazer/developer/trace/focusable.rb
-- lib/trailblazer/developer/trace/inspector.rb
+- lib/trailblazer/developer/trace/debugger.rb
+- lib/trailblazer/developer/trace/debugger/normalizer.rb
 - lib/trailblazer/developer/trace/present.rb
+- lib/trailblazer/developer/trace/stack.rb
+- lib/trailblazer/developer/trace/tree.rb
 - lib/trailblazer/developer/version.rb
 - lib/trailblazer/developer/wtf.rb
 - lib/trailblazer/developer/wtf/renderer.rb
 - trailblazer-developer.gemspec
-homepage: http://trailblazer.to
+homepage: http://trailblazer.to/2.1/docs/trailblazer.html#trailblazer-developer
 licenses:
 - LGPL-3.0
 metadata: {}

data/gems.local.rb

@@ -1,11 +0,0 @@
-source "https://rubygems.org"
-
-# Specify your gem's dependencies in trailblazer-developer.gemspec
-gemspec
-
-gem "trailblazer-activity", path: "../trailblazer-activity"
-gem "trailblazer-activity-dsl-linear", path: "../trailblazer-activity-dsl-linear"
-gem "representable"
-gem 'pry-byebug'
-gem "faraday"
-gem "multi_json"

data/lib/trailblazer/developer/trace/focusable.rb

@@ -1,78 +0,0 @@
-module Trailblazer
-  module Developer
-    module Trace
-
-      module Focusable
-        module_function
-
-        # Get inspect of {focus_on.variables} or current {ctx}
-        def capture_variables_from(ctx, focus_on:, inspector: Trace::Inspector, **flow_options)
-          # ctx keys to be captured, for example [:current_user, :model, ....]
-          variables = (selected = focus_on[:variables]).any? ? selected : ctx.keys
-
-          variables.each_with_object({}) do |variable, result|
-            if variable.is_a?(Proc) # To allow deep key access from ctx
-              result[:Custom]   = inspector.(variable.call(ctx), **flow_options)
-            else
-              result[variable]  = inspector.(ctx[variable], **flow_options)
-            end
-          end
-        end
-
-        # Generate Hirb's vertical table nodes from captured ctx of each step
-        # |-- some step name
-        # |   |-- ********** Input **********
-        #    message: "WTF!"
-        #        seq: []
-        # |   `-- ********** Output **********
-        #    message: "WTF!"
-        #        seq: [:a]
-        def tree_nodes_for(level, input:, output:, **options)
-          # TODO: Reverting `Hash#compact` usage as it is not supported in Ruby <= 2.4
-          # Once the support is droped, revert actual code with below and remove entity check.
-          # input_output_nodes = { Input: input, Output: output }.compact.collect do |table_header, entity|
-
-          input_output_nodes = { Input: input, Output: output }.collect do |table_header, entity|
-            next unless entity
-            next unless Array( entity.data[:focused_variables] ).any?
-
-            table = vertical_table_for(entity.data[:focused_variables], table_header: table_header)
-            Present::TreeNodes::Node.new(level + 1, table, input, output, options).freeze
-          end
-
-          input_output_nodes.compact
-        end
-
-        # @private
-        def vertical_table_for(focused_variables, table_header:)
-          patched_vertical_table.render(
-            Array[ focused_variables ],
-            description: nil,
-            table_header: table_header, # Custom option, not from Hirb
-          )
-        end
-
-        # Overrding `Hirb::Helpers::VerticalTable#render_rows` because there is no option
-        # to customize vertical table's row header :(
-        # We need it to print if given entity is Input/Output
-        #
-        # @private
-        def patched_vertical_table
-          table = Class.new(Hirb::Helpers::VerticalTable)
-
-          table.send(:define_method, :render_rows) do
-            longest_header = Hirb::String.size (@headers.values.sort_by {|e| Hirb::String.size(e) }.last || '')
-            stars = "*" * [(longest_header + (longest_header / 2)), 3].max
-
-            @rows.map do |row|
-              "#{stars} #{@options[:table_header]} #{stars}\n" +
-                @fields.map{ |f| "#{Hirb::String.rjust(@headers[f], longest_header)}: #{row[f]}" }.join("\n")
-            end
-          end
-
-          table
-        end
-      end
-    end
-  end
-end