trailblazer-developer 0.0.25 → 0.0.27

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e213c664a285173ad64b7236f17a026dda9159c7e53c4e595f5c9b36a3bcd15
-  data.tar.gz: 2beca5ea9fb78c56263302c7dee6a5566e798b5a40db737283a63dcb5a35295c
+  metadata.gz: 45cd9fac3c0701cd0e98573e27c59c80de31d5d91b306980c961d58f64161d71
+  data.tar.gz: 745d4d28834261571fdbccc9949b597bb1f17f669bc238a6bbc09925001d4594
 SHA512:
-  metadata.gz: ff33e213922bb017b4b9b6ba4b9a26cd7fb359437a03ed20902c9667cd593a026763253880fa43f9327858f0f871b95e3919e1247f49d04446d6c0fd462a490d
-  data.tar.gz: 9386d74ddd3f3fcfaa30f74b8a3fb7ed1aad1d692e6f19b28f8555e115dbae6e2c4a765f30d887bae8e5ab30763179aa5488ecb0b8a0833e255cd21c7bb22175
+  metadata.gz: 57bdf494ed795a80edadba06bcc011d9ee5832eb6a4f87f0c02a5a1b0a81b82be05507eb4eb593cd6476b71efb7f9a1a82eced117dcc5e41175d028f5c2c8f0e
+  data.tar.gz: 6735f1eea27c3fa7c87d394d3d0a9baf9c2218f632f8bd2d2b5b9325366a3d5ff47a5e89668bd8146429e8ef00ad814b9593fa0e8fbea7519dbe3dd345ae14bd

data/.github/workflows/ci.yml

@@ -1,3 +1,6 @@
+## This file is managed by Terraform.
+## Do not modify this file directly, as it may be overwritten.
+## Please open an issue instead.
 name: CI
 on: [push, pull_request]
 jobs:
@@ -5,13 +8,12 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # Due to https://github.com/actions/runner/issues/849, we have to use quotes for '3.0'
-        ruby: [2.5, 2.6, 2.7, '3.0', head, jruby]
+        ruby: [2.7, '3.0', '3.1']
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby }}
-        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+        bundler-cache: true
     - run: bundle exec rake

data/.github/workflows/ci_jruby.yml

@@ -0,0 +1,19 @@
+## This file is managed by Terraform.
+## Do not modify this file directly, as it may be overwritten.
+## Please open an issue instead.
+name: CI JRuby
+on: [push, pull_request]
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [jruby, jruby-head]
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+    - run: bundle exec rake

data/.github/workflows/ci_legacy.yml

@@ -0,0 +1,19 @@
+## This file is managed by Terraform.
+## Do not modify this file directly, as it may be overwritten.
+## Please open an issue instead.
+name: CI with EOL ruby versions
+on: [push, pull_request]
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [2.5, 2.6]
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+    - run: bundle exec rake

data/.github/workflows/ci_truffleruby.yml

@@ -0,0 +1,19 @@
+## This file is managed by Terraform.
+## Do not modify this file directly, as it may be overwritten.
+## Please open an issue instead.
+name: CI TruffleRuby
+on: [push, pull_request]
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [truffleruby, truffleruby-head]
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+    - run: bundle exec rake

data/CHANGES.md

@@ -1,3 +1,33 @@
+# 0.0.27
+
+## Trace
+
+* `Trace.capture_args` and `capture_return` no longer use any `Graph` logic. This
+  is moved to `Trace::Present` instead to reduce complexity at crunch time.
+* Removed the `:focus_on` option for `#wtf?`. This is now solved through the debugger.
+* `Trace.default_input_collector` and `default_output_collector` now receive the original taskWrap/pipeline-args
+  `[wrap_ctx, original_args]`.
+* In `Trace::Present.call` it's now possible to provide labels to the `default_renderer` using the `:label` option.
+* `Circuit.render` now accepts segments/path.
+* Fixed a bug in `Trace::Present` where the traced top activity would show up as a node, which was wrong.
+* Rename `Trace::Entity` to `Trace::Captured`.
+* Removed `:position` keyword in `Trace::Renderer` and friends.
+* Changed `Trace::Stack` from a nested datastructure to a linear `Captured` stack.
+
+## Debugger
+
+* Add `Debugger::Node` as an interface and datastructure between tracing (`Stack` and `Captured`) and `Present`,
+  the latter now having access to `Debugger::Node`, only.
+* Add `Debugger::Normalizer`, which computes default values for `Debugger::Node` at present-time.
+
+## Internals
+
+* Use `trailblazer-activity-dsl-linear-1.0.0`.
+
+# 0.0.26
+
+* Fixing release, and allow using beta versions.
+
 # 0.0.25
 
 * Use `trailblazer-activity-dsl-linear` >= 1.0.0.beta1. This allows using this gem for testing beta versions.

data/Gemfile

@@ -6,5 +6,5 @@ gemspec
 # gem "trailblazer-activity", ">= 0.7.1"
 # gem "trailblazer-activity", path: "../trailblazer-activity"
 # gem "trailblazer-activity-dsl-linear", path: "../trailblazer-activity-dsl-linear"
-# gem "trailblazer-activity-dsl-linear", github: "trailblazer/trailblazer-activity-dsl-linear"
-# gem "trailblazer-activity", github: "trailblazer/trailblazer-activity"
+gem "trailblazer-activity-dsl-linear", github: "trailblazer/trailblazer-activity-dsl-linear"
+gem "trailblazer-activity", github: "trailblazer/trailblazer-activity"

data/lib/trailblazer/developer/introspect.rb

@@ -0,0 +1,17 @@
+module Trailblazer
+  module Developer
+    module Introspect
+      # find the path for Strategy subclasses.
+      # FIXME: will be removed
+      def self.find_path(activity_class, segments)
+        activity = activity_class.is_a?(Class) ? activity_class.to_h[:activity] : activity_class # FIXME: not a real fan of this, maybe always do {to_h[:activity]}
+
+        node, activity, graph = Activity::Introspect.find_path(activity, segments)
+
+        activity = activity.is_a?(Class) ? activity.to_h[:activity] : activity # FIXME: not a real fan of this, maybe always do {to_h[:activity]}
+
+        return node, activity, graph
+      end
+    end
+  end
+end

data/lib/trailblazer/developer/render/circuit.rb

@@ -11,7 +11,12 @@ module Trailblazer
         module_function
 
         # Render an {Activity}'s circuit as a simple hash.
-        def call(activity, **options)
+        def call(activity, path: nil, **options)
+          if path # TODO: move to place where all renderers can use this logic!
+            node, _, graph   = Developer::Introspect.find_path(activity, path)
+            activity  = node.task
+          end
+
           graph = Activity::Introspect::Graph(activity)
 
           circuit_hash(graph, **options)

data/lib/trailblazer/developer/render/task_wrap.rb

@@ -0,0 +1,79 @@
+module Trailblazer
+  module Developer
+    module Render
+      module TaskWrap
+        # @param activity Trailblazer::Activity
+        def self.render_for(activity, node)
+          task_wrap = task_wrap_for_activity(activity) # TODO: MERGE WITH BELOW
+          task      = node.task
+          step_wrap = task_wrap[task] # the taskWrap for the actual step, e.g. {input,call_task,output}.
+
+          level = 2
+          nodes = render_pipeline(step_wrap, level)
+
+          nodes = [[0, activity], [1, node.id], *nodes]
+
+          Hirb::Console.format_output(nodes, class: :tree, type: :directory, multi_line_nodes: true)
+        end
+
+        # @param activity Activity
+        def self.task_wrap_for_activity(activity, **)
+          activity[:wrap_static]
+        end
+
+        def self.render_pipeline(pipeline, level)
+          renderers = Hash.new(method(:render_task_wrap_step))
+          renderers.merge!(
+            Trailblazer::Activity::DSL::Linear::VariableMapping::Pipe::Input => method(:render_input),
+            Trailblazer::Activity::DSL::Linear::VariableMapping::Pipe::Output => method(:render_input),
+          )
+# TODO: use collect
+          nodes=[]
+
+          pipeline.to_a.collect do |row|
+            renderer = renderers[row[1].class]
+
+            nodes = nodes + renderer.(row, level) # call the rendering component.
+          end
+
+          nodes
+        end
+
+        def self.render_task_wrap_step(row, level)
+          text = row.id.to_s.ljust(33, ".") + row[1].class.to_s
+
+          [[level, text]]
+        end
+
+        def self.render_input(row, level)
+          variable_mapping = Activity::DSL::Linear::VariableMapping
+
+          input_pipe = row[1].instance_variable_get(:@pipe) # this is again a {TaskWrap::Pipeline}.
+
+          filters = input_pipe.to_a.collect do |id, filter|
+            id, class_name, info =
+              if filter.is_a?(variable_mapping::AddVariables) || filter.is_a?(variable_mapping::SetVariable)
+                # TODO: grab user_filter here if needed for understanding
+                # _info       = filter.instance_variable_get(:@user_filter).inspect # we could even grab the source code for callables here!
+                _info       = ""
+
+                [id, filter.class.to_s.match(/VariableMapping::.+/), _info]
+              else # generic VariableMapping::DSL step such as {VariableMapping.scope}
+                _name = filter.inspect.match(/VariableMapping\.\w+/)
+
+                [id.to_s, _name, ""]
+              end
+
+            text =  "#{id.ljust(45, ".")} #{info.ljust(45, ".")} #{class_name}"
+
+            [level+1, text]
+          end
+
+          # pp filters
+          render_task_wrap_step(row, level) + filters
+          # render_task_wrap_step(row, level)
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/developer/trace/debugger/normalizer.rb

@@ -0,0 +1,68 @@
+module Trailblazer
+  module Developer
+    module Trace
+      module Debugger
+        # @private
+        # Public entry point to add Debugger::Node normalizer steps.
+        def self.add_normalizer_step!(step, id:, normalizer: Normalizer::PIPELINES.last, **options)
+          task = Normalizer.Task(step)
+
+          # We have a TaskWrap::Pipeline (a very simple style of "activity" used for normalizers) and
+          # add another step using the "friendly interface" from {Activity::Adds}.
+          options = {append: nil} unless options.any?
+
+          pipeline_extension = Activity::TaskWrap::Extension.build([task, id: id, **options])
+
+          Normalizer::PIPELINES << pipeline_extension.(normalizer)
+        end
+
+        module Normalizer
+          def self.Task(user_step) # TODO: we could keep this in the {activity} gem.
+            Activity::TaskWrap::Pipeline::TaskAdapter.for_step(user_step, option: false) # we don't need Option as we don't have ciruit_options here, and no {:exec_context}
+          end
+
+          # Default steps for the Debugger::Node options pipeline, following the step-interface.
+          module Default
+            def self.compile_id(ctx, task_map_for_activity:, task:, **)
+              ctx[:compile_id] = task_map_for_activity.fetch(task)[:id]
+            end
+
+            def self.compile_path(ctx, parent_map:, captured_node:, **)
+              ctx[:compile_path] = Trace::Tree::ParentMap.path_for(parent_map, captured_node)
+            end
+
+            def self.runtime_id(ctx, compile_id:, **)
+              ctx[:runtime_id] = compile_id
+            end
+
+            def self.runtime_path(ctx, runtime_id:, compile_path:, **)
+              return ctx[:runtime_path] = compile_path if compile_path.empty? # FIXME: this currently only applies to root.
+
+              ctx[:runtime_path] = compile_path[0..-2] + [runtime_id]
+            end
+
+            def self.label(ctx, label: nil, runtime_id:, **)
+              ctx[:label] = label || runtime_id
+            end
+
+            def self.data(ctx, data: {}, **)
+              ctx[:data] = data
+            end
+          end
+
+          default_steps = {
+            compile_id:       Normalizer.Task(Default.method(:compile_id)),
+            compile_path:     Normalizer.Task(Default.method(:compile_path)),
+            runtime_id:       Normalizer.Task(Default.method(:runtime_id)),
+            runtime_path:     Normalizer.Task(Default.method(:runtime_path)),
+            label:            Normalizer.Task(Default.method(:label)),
+            data:             Normalizer.Task(Default.method(:data)),
+          }.
+          collect { |id, task| Activity::TaskWrap::Pipeline.Row(id, task) }
+
+          PIPELINES = [Activity::TaskWrap::Pipeline.new(default_steps)] # we do mutate this constant at compile-time. Maybe # DISCUSS and find a better way.
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+module Trailblazer
+  module Developer
+    module Trace
+      module Debugger
+        class Node < Struct.new(:captured_node, :task, :activity, :compile_id, :compile_path, :runtime_id, :runtime_path, :label, :data, :captured_input, :captured_output, :level, keyword_init: true)
+          # The idea is to only work with {Activity} instances on this level, as that's the runtime concept.
+
+            # TODO: class, "type",
+            # which track, return signal, etc
+
+
+          # we always key options for specific nodes by Stack::Captured::Input, so we don't confuse activities if they were called multiple times.
+          def self.build(tree, enumerable_tree, node_options: {}, normalizer: Debugger::Normalizer::PIPELINES.last, **options_for_nodes)
+            parent_map = Trace::Tree::ParentMap.build(tree).to_h # DISCUSS: can we use {enumerable_tree} for {ParentMap}?
+
+
+            container_activity = enumerable_tree[0].captured_input.activity # TODO: any other way to grab the container_activity? Maybe via {activity.container_activity}?
+
+  # TODO: cache activity graph
+            top_activity = enumerable_tree[0].captured_input.task
+
+            task_maps_per_activity = {
+              container_activity => {top_activity => {id: nil}} # exposes {Introspect::TaskMap}-compatible interface.
+            }
+
+            # DISCUSS: this might change if we introduce a new Node type for Trace.
+            debugger_nodes = enumerable_tree[0..-1].collect do |node|
+              activity      = node.captured_input.activity
+              task          = node.captured_input.task
+              # it's possible to pass per-node options, like {label: "Yo!"} via {:node_options[<captured_input>]}
+              options       = node_options[node.captured_input] || {}
+
+
+
+              task_map_for_activity = task_maps_per_activity[activity] || Activity::Introspect.TaskMap(activity)
+
+              options_for_debugger_node, _ = normalizer.(
+                {
+                  captured_node:          node,
+                  task:                   task,
+                  activity:               activity,
+                  parent_map:             parent_map,
+                  task_map_for_activity:  task_map_for_activity,
+                  **options
+                },
+                []
+              )
+
+              options_for_debugger_node = options_for_debugger_node.slice(*(options_for_debugger_node.keys - [:parent_map, :task_map_for_activity]))
+
+              # these attributes are not changing with the presentation
+              Debugger::Node.new(
+                captured_node:  node,
+                activity:       activity,
+                task:           task,
+
+                level: node.level,
+                captured_input: node.captured_input,
+                captured_output: node.captured_output,
+
+                **options_for_debugger_node,
+              ).freeze
+            end
+          end
+
+          def self.build_for_stack(stack, **options_for_debugger_nodes)
+            tree, processed = Trace.Tree(stack.to_a)
+
+            enumerable_tree = Trace::Tree.Enumerable(tree)
+
+            Debugger::Node.build(
+              tree,
+              enumerable_tree,
+              **options_for_debugger_nodes,
+            )
+          end
+        end
+      end # Debugger
+    end # Trace
+  end
+end

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

@@ -1,63 +1,45 @@
-require 'hirb'
+require "hirb"
 
 module Trailblazer::Developer
   module Trace
     module Present
       module_function
 
-      def default_renderer(task_node:, **)
-        [ task_node.level, %{#{task_node.value}} ]
+      # @private
+      def default_renderer(debugger_node:, **) # DISCUSS: for compatibility, should we pass {:task_node} here, too?
+        [debugger_node.level, debugger_node.label]
       end
 
-      def call(stack, level: 1, tree: [], renderer: method(:default_renderer), **options)
-        tree(stack.to_a, level, tree: tree, renderer: renderer, **options)
-      end
-
-      def tree(stack, level, tree:, renderer:, **options)
-        opts = options.merge(tree: tree)
-        tree_for(stack, level, **opts)
-
-        nodes = tree.each_with_index.map do |task_node, position|
-          renderer.(task_node: task_node, position: position, tree: tree)
+      # Returns the console output string.
+      # @private
+      def render(debugger_nodes, renderer: method(:default_renderer), **options_for_renderer)
+        nodes = debugger_nodes.collect do |debugger_node|
+          renderer.(debugger_node: debugger_node, tree: debugger_nodes, **options_for_renderer)
         end
 
         Hirb::Console.format_output(nodes, class: :tree, type: :directory, multi_line_nodes: true)
       end
 
-      def tree_for(stack, level, tree:, **options)
-        stack.each do |lvl| # always a Stack::Task[input, ..., output]
-          input, output, nested = Trace::Level.input_output_nested_for_level(lvl)
+      # Entry point for rendering a Stack as a "tree branch" the way we do it in {#wtf?}.
+      def call(stack, render_method: method(:render), node_options: {}, **options)
+        # The top activity doesn't have an ID, hence we need to compute a default label.
+        # TODO: maybe we should deep-merge here.
+        captured_input_for_top_activity = stack.to_a[0]
 
-          tree.push(*TreeNodes.for(level, **options.merge(input: input, output: output)))
+        top_activity_options = {
+          # we can pass particular label "hints".
+          captured_input_for_top_activity => {
+            # label: %{#{captured_input_for_top_activity.task.superclass} (anonymous)},
+            label: captured_input_for_top_activity.task.inspect,
+          },
+        }
 
-          if nested.any? # nesting
-            opts = options.merge(tree: tree)
-            tree_for(nested, level + 1, **opts)
-          end
+        node_options = top_activity_options.merge(node_options)
 
-          tree
-        end
-      end
+        debugger_nodes = Debugger::Node.build_for_stack(stack, node_options: node_options, **options) # currently, we agree on using a Debugger::Node list as the presentation data structure.
 
-      module TreeNodes
-        Node = Struct.new(:level, :value, :input, :output, :options) do
-          # Allow access to any custom key from options, eg. color_map
-          def method_missing(name, *)
-            options[name]
-          end
-        end
-
-        module_function
-
-        def for(level, input:, output:, **options)
-          nodes = Array[ Node.new(level, input.data[:task_name], input, output, options).freeze ]
-
-          focused_nodes = Trace::Focusable.tree_nodes_for(level, input: input, output: output, **options)
-          nodes += focused_nodes if focused_nodes.length > 0
-
-          nodes
-        end
+        return render_method.(debugger_nodes, **options)
       end
-    end
+    end # Present
   end
 end

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

@@ -0,0 +1,21 @@
+module Trailblazer
+  module Developer
+    module Trace
+      # The stack is a linear one-dimensional array. Per traced task two {Trace::Captured}
+      # elements get pushed onto it (unless there's an Exception).
+      class Stack
+        def initialize(captureds=[])
+          @stack = captureds
+        end
+
+        def <<(captured)
+          @stack << captured
+        end
+
+        def to_a
+          @stack
+        end
+      end # Stack
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+module Trailblazer
+  module Developer
+    module Trace
+      # Datastructure representing a trace.
+      class Tree
+        # This could also be seen as {tree.to_a}.
+        def self.Enumerable(node)
+          Enumerable.nodes_for(node)
+        end
+
+        module Enumerable
+          # @private
+          def self.nodes_for(node)
+            [node, *node.nodes.collect { |n| nodes_for(n) } ].flatten
+          end
+        end # Enumerable
+
+        # Map each {Node} instance to its parent {Node}.
+        module ParentMap
+          def self.build(node)
+            children_map = []
+            node.nodes.each { |n| children_map += ParentMap.build(n) }#.flatten(1)
+
+            node.nodes.collect { |n| [n, node] } + children_map
+          end
+
+          # @public
+          def self.path_for(parent_map, node)
+            path = []
+
+            while parent = parent_map[node] # DISCUSS: what if the graphs are cached and present, already?
+              node_id = Activity::Introspect::TaskMap(node.captured_input.activity)[node.captured_input.task][:id]
+              path << node_id
+
+              node = parent
+            end
+
+            path.reverse
+          end
+        end
+
+        class Node < Struct.new(:level, :captured_input, :captured_output, :nodes)
+        end
+      end # Tree
+
+
+      # Builds a tree graph from a linear stack.
+      # Consists of {Tree::Node} structures.
+      def self.Tree(stack_end, level: 0, parent: nil)
+        processed = []
+        nodes     = []
+
+        # for {captured_input} we're gonna build a {Node}!
+        captured_input, remaining = stack_end[0], stack_end[1..-1]
+
+            raise unless captured_input.is_a?(Captured::Input)
+
+        while next_captured = remaining[0]
+          if next_captured.is_a?(Captured::Input)
+
+            bla, _processed = Tree(remaining, level: level+1)
+            nodes += [bla]
+            processed += _processed
+
+
+            remaining = remaining - processed
+
+          else # Captured::Output
+
+            raise unless next_captured.is_a?(Captured::Output)
+            raise if next_captured.activity != captured_input.activity
+
+            node = Tree::Node.new(level, captured_input, next_captured, nodes)
+
+            return node,
+              [captured_input, *processed, next_captured] # what nodes did we process here?
+
+          end
+
+        end
+
+
+      end # Tree
+    end
+  end # Developer
+end

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.25"
+      VERSION = "0.0.27"
     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,12 +6,16 @@ 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"

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,9 @@ 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"
 
-  spec.add_dependency "trailblazer-activity-dsl-linear", ">= 1.0.0.beta1", "< 1.1.0"
+  spec.add_dependency "trailblazer-activity-dsl-linear", ">= 1.1.0", "< 1.2.0"
+  # FIXME: Activity 0.14.1
   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.25
+  version: 0.0.27
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-07-19 00:00:00.000000000 Z
+date: 2022-12-14 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'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '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.1.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: 1.1.0
+        version: 1.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.0.beta1
+        version: 1.1.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: 1.1.0
+        version: 1.2.0
 - !ruby/object:Gem::Dependency
   name: hirb
   requirement: !ruby/object:Gem::Requirement
@@ -108,6 +122,9 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/ci.yml"
+- ".github/workflows/ci_jruby.yml"
+- ".github/workflows/ci_legacy.yml"
+- ".github/workflows/ci_truffleruby.yml"
 - ".gitignore"
 - CHANGES.md
 - Gemfile
@@ -116,19 +133,22 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
-- gems.local.rb
 - lib/trailblazer/developer.rb
+- lib/trailblazer/developer/introspect.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

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

@@ -1,48 +0,0 @@
-module Trailblazer
-  module Developer
-    module Trace
-
-      # This module does the inspection of given `ctx` with deep traversal.
-      # It only gets called when focusing is going on (i.e. focus_on API).
-      module Inspector
-        module_function
-
-        def call(value, default_inspector: method(:default_inspector), **)
-          return hash_inspector(value, default_inspector: default_inspector) if value.is_a?(Hash)
-          return array_inspector(value, default_inspector: default_inspector) if value.is_a?(Array)
-
-          default_inspector.(value)
-        end
-
-        def hash_inspector(value, default_inspector:)
-          Hash[
-            value.collect do |key, nested_value|
-              [key, call(nested_value, default_inspector: default_inspector)]
-            end
-          ]
-        end
-
-        def array_inspector(value, default_inspector:)
-          value.collect do |nested_value|
-            call(nested_value, default_inspector: default_inspector)
-          end
-        end
-
-        # To avoid additional query that AR::Relation#inspect makes,
-        # we're calling AR::Relation#to_sql to get plain SQL string instead.
-        def activerecord_relation_inspector(value)
-          { query: value.to_sql }
-        end
-
-        def default_inspector(value)
-          if defined?(ActiveRecord) && value.is_a?(ActiveRecord::Relation)
-            return activerecord_relation_inspector(value)
-          end
-
-          value.inspect
-        end
-      end
-
-    end
-  end
-end