Class: Woods::FlowDocument

Inherits:
Object
  • Object
show all
Defined in:
lib/woods/flow_document.rb

Overview

Value object representing an assembled execution flow trace.

Contains an ordered list of steps from an entry point through the dependency graph, with each step holding operations extracted from source code in line order.

Examples:

Creating and serializing a flow document

doc = FlowDocument.new(
  entry_point: "PostsController#create",
  route: { verb: "POST", path: "/posts" },
  max_depth: 5,
  steps: [{ unit: "PostsController#create", type: "controller", operations: [...] }]
)
doc.to_h        # => JSON-serializable Hash
doc.to_markdown  # => human-readable table

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(entry_point:, route: nil, max_depth: 5, steps: [], generated_at: nil) ⇒ FlowDocument

Returns a new instance of FlowDocument.

Parameters:

  • entry_point (String) —

    The entry point identifier (e.g., “PostsController#create”)

  • route (Hash, nil) (defaults to: nil) —

    Route info with :verb and :path keys

  • max_depth (Integer) (defaults to: 5) —

    Maximum recursion depth used during assembly

  • steps (Array<Hash>) (defaults to: []) —

    Ordered list of step hashes

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

    ISO8601 timestamp (defaults to now)



29
30
31
32
33
34
35
 
# File 'lib/woods/flow_document.rb', line 29

def initialize(entry_point:, route: nil, max_depth: 5, steps: [], generated_at: nil)
  @entry_point = entry_point
  @route = route
  @max_depth = max_depth
  @steps = steps
  @generated_at = generated_at || Time.now.iso8601
end

Instance Attribute Details

#entry_point ⇒ Object (readonly)

Returns the value of attribute entry_point.



22
23
24
 
# File 'lib/woods/flow_document.rb', line 22

def entry_point
  @entry_point
end

#generated_at ⇒ Object (readonly)

Returns the value of attribute generated_at.



22
23
24
 
# File 'lib/woods/flow_document.rb', line 22

def generated_at
  @generated_at
end

#max_depth ⇒ Object (readonly)

Returns the value of attribute max_depth.



22
23
24
 
# File 'lib/woods/flow_document.rb', line 22

def max_depth
  @max_depth
end

#route ⇒ Object (readonly)

Returns the value of attribute route.



22
23
24
 
# File 'lib/woods/flow_document.rb', line 22

def route
  @route
end

#steps ⇒ Object (readonly)

Returns the value of attribute steps.



22
23
24
 
# File 'lib/woods/flow_document.rb', line 22

def steps
  @steps
end

Class Method Details

.from_h(data) ⇒ FlowDocument

Reconstruct a FlowDocument from a serialized Hash.

Handles both symbol and string keys for JSON round-trip compatibility.

Parameters:

  • data (Hash) —

    Previously serialized flow document data

Returns:



56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/woods/flow_document.rb', line 56

def self.from_h(data)
  data = deep_symbolize_keys(data)

  new(
    entry_point: data[:entry_point],
    route: data[:route],
    max_depth: data[:max_depth] || 5,
    steps: data[:steps] || [],
    generated_at: data[:generated_at]
  )
end

Instance Method Details

#to_h ⇒ Hash

Serialize to a JSON-compatible Hash.

Returns:

  • (Hash) —

    Complete flow document data



40
41
42
43
44
45
46
47
48
 
# File 'lib/woods/flow_document.rb', line 40

def to_h
  {
    entry_point: @entry_point,
    route: @route,
    max_depth: @max_depth,
    generated_at: @generated_at,
    steps: @steps
  }
end

#to_markdown ⇒ String

Render as human-readable Markdown.

Produces a document with a header showing the route and entry point, followed by one section per step with an operations table.

Returns:

  • (String) —

    Markdown-formatted flow document



88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/woods/flow_document.rb', line 88

def to_markdown
  lines = []
  lines << format_header
  lines << ''

  @steps.each_with_index do |step, idx|
    lines << format_step(step, idx + 1)
    lines << ''
  end

  lines.join("\n")
end