trailblazer-developer 0.0.27 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45cd9fac3c0701cd0e98573e27c59c80de31d5d91b306980c961d58f64161d71
-  data.tar.gz: 745d4d28834261571fdbccc9949b597bb1f17f669bc238a6bbc09925001d4594
+  metadata.gz: 343ca726bbb8da50f05aca2a552f018ac67683d4c0021226f828a30132ecf85c
+  data.tar.gz: f4ab036e3da016ab3283f258c749ef98cee474a9c69b8303fad36bdd9b6df945
 SHA512:
-  metadata.gz: 57bdf494ed795a80edadba06bcc011d9ee5832eb6a4f87f0c02a5a1b0a81b82be05507eb4eb593cd6476b71efb7f9a1a82eced117dcc5e41175d028f5c2c8f0e
-  data.tar.gz: 6735f1eea27c3fa7c87d394d3d0a9baf9c2218f632f8bd2d2b5b9325366a3d5ff47a5e89668bd8146429e8ef00ad814b9593fa0e8fbea7519dbe3dd345ae14bd
+  metadata.gz: f66fa880eb4a0673fd881598fe9fa9addebadbd4989fded9366f7960b7ed9ab34794fe8d8a6c4ab3a315b13fe45b048061ac4f4330cb71942a82a3adc1d12a82
+  data.tar.gz: 7ecac119ec1d406442e1ddb5292639bac41e13df24d870f462065d90d5bf690ab4417b0736c9a134b51c2d2929a6952912803cfe2686cfca7d7b16bc14cfaa4a

data/.github/workflows/ci.yml

@@ -1,6 +1,3 @@
-## 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:
@@ -8,7 +5,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: [2.7, '3.0', '3.1']
+        ruby: [2.6, 2.7, '3.0', '3.1', '3.2', 'jruby']
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v3

data/CHANGES.md

@@ -1,3 +1,87 @@
+# 0.1.0
+
+* Improvement of tracing performance: factor ~4.
+* Consistent interface for tracing and presentation.
+
+## Adding `Debugger` layer
+
+* Introduce `Debugger::Trace` with `Trace::Node`s and `variable_versions` field
+  to maintain all data produced by tracing in one entity.
+* In `Trace::Present.call`, you need to pass a block with options for customization instead
+  of passing `:node_options`. Further on, the per-node customization is now keyed by
+  `Trace::Node` instance and not a Stack element anymore.
+* In `render_method`, remove `:tree` keyword argument, use `:debugger_trace`.
+* The `render_method` is called with keyword arguments, only. The first positional argument
+  `debugger_nodes` is now `:debugger_trace`.
+
+  ```ruby
+  output = Dev::Trace::Present.(
+    stack,
+    node_options: {
+      stack.to_a[0] => {label: "Create"}
+    }
+  )
+  ```
+  is now
+
+  ```ruby
+   Dev::Trace::Present.(stack) do |trace_nodes:, **|
+    {
+      node_options: {
+        trace_nodes[0] => {label: "Create"}
+      }
+    }
+  end
+  ```
+
+## `Trace::Node`
+
+* `Node.build_for_stack` is now called in `Trace::Present` and produces a list
+  of `Trace::Node` instances that are containers for  matching before and after snapshots.
+* Add `Node::Incomplete` nodes that have no `snapshot_after` as they represent
+  a part of the flow that was canceled.
+
+## Debugger::Normalizer
+
+* Deprecate `:captured_node` keyword argument in normalizer steps and
+  rename it to `:trace_node`.
+* Remove the concept of `:runtime_path` and `:compile_path`. You can always
+  compute paths after or during the debug rendering yourself. However, we simply
+  don't need it for IDE or wtf?.
+
+## `Trace.wtf?`
+
+* Rename `:output_data_collector` and `:input_data_collector` to `:after_snapshooter` and `:before_snapshooter`
+  as they both produce instances of `Snapshot`. The return signature has changed, the snapshooters
+  return two values now: the data object and an object representing the variable versioning.
+
+## Snapshot
+
+* Introduce the concept of `Snapshot` which can be a moment in time before or after a step.
+  The `Snapshot::Before` and `Snapshot::After` (renamed from `Captured::Input` and `Captured::Output`)
+  are created during the tracing and after tracing associated to a specific `Trace::Node`.
+* Add `Snapshot::Ctx` and `Snapshot::Versions` which is a new, faster way of capturing variables.
+  Instead of always calling `ctx.inspect` for every trace step, only variables that have changed
+  are snapshooted using the (configurable) `:value_snapshooter`. This improves `#wtf?` performance
+  up to factor 10.
+
+# 0.0.29
+
+* The `:render_method` callable can now return output along with additional returned values.
+* Pass the top-level `:activity` into the `:render_method`.
+* In `#wtf?`, only complete the stack when an exception occurred.
+* `wtf?` now returns all original return values plus the computed output from `:render_method`,
+  followed by an arbitrary object from the rendering code.
+
+# 0.0.28
+
+* Move `Introspect::Graph` over from `trailblazer-activity`. It's a data structure very specific
+  to rendering, which is not a part of pure runtime behavior.
+* Use `Introspect.Nodes` API instead of `TaskMap`.
+* Remove `:task_maps_per_activity` in `Debugger` as we don't need to cache anymore.
+* Require `trailblazer-activity-dsl-linear-1.2.0`.
+* Remove `Render::Circuit` as this is part of `trailblazer-activity` now.
+
 # 0.0.27
 
 ## Trace

data/Gemfile

@@ -3,8 +3,13 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in trailblazer-developer.gemspec
 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",             path: "../trailblazer-activity"
+# gem "trailblazer-activity-dsl-linear",  path: "../trailblazer-activity-dsl-linear"
+# gem "trailblazer-operation",            path: "../trailblazer-operation"
+# gem "trailblazer-pro",                  path: "../trailblazer-pro"
+
+# gem "trailblazer-activity",           github: "trailblazer/trailblazer-activity"
+# gem "trailblazer-activity-dsl-linear", github: "trailblazer/trailblazer-activity-dsl-linear"
+
+
+gem "benchmark-ips"

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

@@ -0,0 +1,60 @@
+module Trailblazer
+  module Developer
+    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
+
+      # Run at runtime when preparing a Trace::Nodes for presentation.
+      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, activity:, task:, **)
+            ctx[:compile_id] = Activity::Introspect.Nodes(activity, task: task)[:id]
+          end
+
+          def self.runtime_id(ctx, compile_id:, **)
+            ctx[:runtime_id] = compile_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
+
+          def self.incomplete?(ctx, trace_node:, **)
+            ctx[:incomplete?] = trace_node.is_a?(Developer::Trace::Node::Incomplete)
+          end
+        end
+
+        default_steps = {
+          compile_id:       Normalizer.Task(Default.method(:compile_id)),
+          runtime_id:       Normalizer.Task(Default.method(:runtime_id)),
+          label:            Normalizer.Task(Default.method(:label)),
+          data:             Normalizer.Task(Default.method(:data)),
+          incomplete?:      Normalizer.Task(Default.method(:incomplete?)),
+        }.
+        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

data/lib/trailblazer/developer/debugger.rb

@@ -0,0 +1,97 @@
+module Trailblazer
+  module Developer
+    # Code in Debugger is only executed if the user wants to render the stack.
+    module Debugger
+      ATTRS = [
+        :id,
+        :trace_node,
+        :task,
+        :activity,
+        :compile_id,
+        :runtime_id,
+        :label,
+        :data,
+        :snapshot_before,
+        :snapshot_after,
+        :level,
+        :incomplete?,
+        :captured_node, # TODO: remove once macro is 2.2
+      ]
+
+      # The {Debugger::Node} is an abstraction between Trace::Node and the actual rendering layer (why?)
+      #
+      # TODO: class, "type",
+      # which track, return signal, etc
+      class Node < Struct.new(*ATTRS, keyword_init: true)
+        # we always key options for specific nodes by Stack::Captured::Input, so we don't confuse activities if they were called multiple times.
+        #
+        # @return [Debugger::Node] array of Debugger::Node
+        def self.build(trace_nodes, node_options: {}, normalizer: Debugger::Normalizer::PIPELINES.last, **options_for_nodes)
+          # DISCUSS: this might change if we introduce a new Node type for Trace.
+          _debugger_nodes = trace_nodes.collect do |trace_node|
+            # it's possible to pass per-node options, like {label: "Yo!"} via {:node_options[<snapshot_before>]}
+            options_from_user  = node_options[trace_node] || {}
+
+            options_from_trace_node = trace_node
+              .to_h # :level, :snapshot_before, :snapshot_after
+              .merge(
+                id:           trace_node.object_id,
+                trace_node:   trace_node,
+                activity:     trace_node.snapshot_before.activity,
+                task:         trace_node.task,
+                captured_node: DeprecatedCapturedNode, # TODO: remove once macro is 2.2
+              )
+
+            options_for_debugger_node, _ = normalizer.(
+              {
+                **options_from_trace_node,
+                **options_from_user
+              },
+              []
+            )
+
+            # these attributes are not changing with the presentation
+            Debugger::Node.new(**options_for_debugger_node).freeze
+          end
+        end
+
+        # TODO: remove once macro is 2.2
+        class DeprecatedCapturedNode
+          def self.method_missing(*)
+            raise "[Trailblazer] The `:captured_node` argument is deprecated, please upgrade to `trailblazer-developer-0.1.0` and use `:trace_node` if the upgrade doesn't fix it."
+          end
+        end
+      end # Node
+
+      # Interface for data (nodes, versions, etc) between tracing code and presentation layer.
+      # We have no concept of {Stack} here anymore. Nodes and arbitrary objects such as "versions".
+      # Debugger::Trace interface abstracts away the fact we have two snapshots. Here,
+      # we only have a node per task.
+      #
+      class Trace
+        # Called in {Trace::Present}.
+        # Design note: goal here is to have as little computation as possible.
+        def self.build(stack, trace_nodes, **options_for_debugger_nodes)
+          nodes = Debugger::Node.build(
+            trace_nodes,
+            **options_for_debugger_nodes,
+          )
+
+          new(nodes: nodes, variable_versions: stack.variable_versions) # after this, the concept of "Stack" doesn't exist anymore.
+        end
+
+        def initialize(nodes:, variable_versions:)
+          @options = {nodes: nodes, variable_versions: variable_versions}
+        end
+
+        def to_h
+          @options
+        end
+
+        def to_a
+          to_h[:nodes].to_a
+        end
+      end
+    end # Debugger
+  end
+end

data/lib/trailblazer/developer/introspect/graph.rb

@@ -0,0 +1,83 @@
+# NOTE: The Graph API might get deprecated and replaced.
+module Trailblazer
+  module Developer
+    module Introspect
+      # TODO: order of step/fail/pass in Node would be cool to have
+
+      # TODO: Remove Graph. This is only useful to render the full circuit
+      # Some thoughts here:
+      # * where do we need Schema.outputs? and where task.outputs?
+      #
+      #
+      # @private This API is still under construction.
+      class Graph
+        def initialize(activity)
+          @schema   = activity.to_h or raise
+          @circuit  = @schema[:circuit]
+          @map      = @circuit.to_h[:map]
+          @configs  = @schema[:nodes]
+        end
+
+        def find(id = nil, &block)
+          return find_by_id(id) unless block_given?
+
+          find_with_block(&block)
+        end
+
+        # TODO: convert to {#to_a}.
+        def collect(strategy: :circuit)
+          @map.keys.each_with_index.collect { |task, i| yield find_with_block { |node| node.task == task }, i }
+        end
+
+        def stop_events
+          @circuit.to_h[:end_events]
+        end
+
+        private
+
+        def find_by_id(id)
+          node = @configs.find { |_, _node| _node.id == id } or return
+          node_for(node[1])
+        end
+
+        def find_with_block
+          existing = @configs.find { |_, node| yield Node(node.task, node.id, node.outputs, node.data) } or return
+
+          node_for(existing[1])
+        end
+
+        # Build a {Graph::Node} with outputs etc.
+        def node_for(node_attributes)
+          Node(
+            node_attributes.task,
+            node_attributes.id,
+            node_attributes.outputs, # [#<struct Trailblazer::Activity::Output signal=Trailblazer::Activity::Right, semantic=:success>]
+            outgoings_for(node_attributes),
+            node_attributes.data,
+          )
+        end
+
+        def Node(*args)
+          Node.new(*args).freeze
+        end
+
+        Node     = Struct.new(:task, :id, :outputs, :outgoings, :data)
+        Outgoing = Struct.new(:output, :task)
+
+        def outgoings_for(node)
+          outputs     = node.outputs
+          connections = @map[node.task]
+
+          connections.collect do |signal, target|
+            output = outputs.find { |out| out.signal == signal }
+            Outgoing.new(output, target)
+          end
+        end
+      end
+
+      def self.Graph(*args)
+        Graph.new(*args)
+      end
+    end # Graph
+  end
+end

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

@@ -2,61 +2,13 @@ module Trailblazer
   module Developer
     module_function
 
-    def render(activity, **options)
-      Render::Circuit.(activity, **options)
-    end
-
-    module Render
-      module Circuit
-        module_function
-
-        # Render an {Activity}'s circuit as a simple hash.
-        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)
-        end
-
-        def circuit_hash(graph, **options)
-          content = graph.collect do |node|
-            conns = node.outgoings.collect do |outgoing|
-              " {#{outgoing.output.signal}} => #{inspect_with_matcher(outgoing.task, **options)}"
-            end
-
-            [ inspect_with_matcher(node.task, **options), conns.join("\n") ]
-          end
-
-          content = content.join("\n")
-
-          "\n#{content}".gsub(/0x\w+/, "0x")
-        end
-
-        # If Ruby had pattern matching, this function wasn't necessary.
-        def inspect_with_matcher(task, inspect_task: method(:inspect_task), inspect_end: method(:inspect_end))
-          return inspect_task.(task) unless task.kind_of?(Trailblazer::Activity::End)
-          inspect_end.(task)
-        end
-
-        def inspect_task(task)
-          task.inspect
-        end
-
-        def inspect_end(task)
-          class_name = Render::Circuit.strip(task.class)
-          options    = task.to_h
-
-          "#<#{class_name}/#{options[:semantic].inspect}>"
-        end
-
-        def self.strip(string)
-          string.to_s.sub("Trailblazer::Activity::", "")
-        end
+    def render(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
+
+      Activity::Introspect::Render.(activity, **options)
     end
   end
 end

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

@@ -15,7 +15,7 @@ module Trailblazer
         module_function
 
         def call(operation, style: :line)
-          graph = Activity::Introspect::Graph(operation)
+          graph = Introspect::Graph(operation)
 
           rows = graph.collect do |node, i|
             next if node[:data][:stop_event] # DISCUSS: show this?

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

@@ -18,7 +18,7 @@ module Trailblazer
 
         # @param activity Activity
         def self.task_wrap_for_activity(activity, **)
-          activity[:wrap_static]
+          activity.to_h[:config][:wrap_static]
         end
 
         def self.render_pipeline(pipeline, level)

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

@@ -0,0 +1,103 @@
+module Trailblazer
+  module Developer
+    module Trace
+      # Build array of {Trace::Node} from a snapshots stack.
+      # @private
+      def self.build_nodes(snapshots)
+        instructions = [
+          [0, snapshots]
+        ]
+
+        _nodes = Node.process_instructions(instructions)
+      end
+
+      # Datastructure representing a trace.
+      class Node < Struct.new(:level, :task, :snapshot_before, :snapshot_after)
+        class Incomplete < Node
+        end
+
+        def self.pop_from_instructions!(instructions)
+          while (level, remaining_snapshots = instructions.pop)
+            next if level.nil?
+            next if remaining_snapshots.empty?
+
+            return level, remaining_snapshots
+          end
+
+          false
+        end
+
+        # def self.BLA(instructions)
+        #   instructions.collect do |(level, remaining_snapshots)|
+        #     [
+        #       level,
+        #       remaining_snapshots.collect { |snap| [snap.class, snap.task] }
+        #     ]
+        #   end
+        # end
+
+        def self.process_instructions(instructions) # FIXME: mutating argument
+          nodes = []
+
+          while (level, remaining_snapshots = pop_from_instructions!(instructions))
+            raise unless remaining_snapshots[0].is_a?(Snapshot::Before) # DISCUSS: remove assertion?
+
+            node, new_instructions = node_and_instructions_for(remaining_snapshots[0], remaining_snapshots[1..-1], level: level)
+            # pp BLA(new_instructions)
+
+            nodes << node
+
+            instructions += new_instructions
+          end
+
+          return nodes
+        end
+
+        # Called per snapshot_before   "process_branch"
+        # 1. Find, for snapshot_before, the matching snapshot_after in the stack
+        # 2. Extract snapshots inbetween those two. These are min. 1 level deeper in!
+        # 3. Run process_siblings for 2.
+        def self.node_and_instructions_for(snapshot_before, descendants, level:)
+          # Find closing snapshot for this branch.
+          snapshot_after = descendants.find do |snapshot|
+            snapshot.is_a?(Snapshot::After) && snapshot.data[:snapshot_before] == snapshot_before
+          end
+
+          if snapshot_after
+            snapshot_after_index = descendants.index(snapshot_after)
+
+            instructions =
+              if snapshot_after_index == 0 # E.g. before/Start, after/Start
+                [
+                  [level, descendants[1..-1]]
+                ]
+              else
+                nested_instructions = [
+                  # instruction to go through the remaining, behind this tuple.
+                  [
+                    level,
+                    descendants[(snapshot_after_index + 1)..-1]
+                  ],
+                  # instruction to go through all snapshots between this current tuple.
+                  [
+                    level + 1,
+                    descendants[0..snapshot_after_index - 1], # "new descendants"
+                  ],
+                ]
+              end
+
+            node = new(level, snapshot_before.task, snapshot_before, snapshot_after)
+          else # incomplete
+            instructions = [
+              [level + 1, descendants]
+            ]
+
+            node = Incomplete.new(level, snapshot_before.task, snapshot_before, nil)
+          end
+
+          return node, instructions
+        end
+      end # Node
+    end
+  end # Developer
+end

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

@@ -0,0 +1,32 @@
+module Trailblazer
+  module Developer
+    module Trace
+      # Map each {Node} instance to its parent {Node}.
+      module ParentMap # DISCUSS: where does this belong?
+        def self.build(trace_nodes)
+          levels = {}
+          trace_nodes.collect do |node|
+            level = node.level
+            levels[level] = node
+
+            [node, levels[level - 1]]
+          end.to_h
+        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.Nodes(node.snapshot_before.activity, task: node.snapshot_before.task).id
+            path << node_id
+
+            node = parent
+          end
+
+          path.reverse
+        end
+      end # ParentMap
+    end
+  end # Developer
+end