User specifies entry point
  │  e.g., "CheckoutsController#create"
  │
  ▼
┌─────────────────────────────────────────────────────┐
│ FlowAssembler                                       │
│                                                     │
│  1. Load unit source from extracted data            │
│  2. Parse method body AST                           │
│  3. Extract operations in source line order         │
│  4. Resolve calls to other ExtractedUnits           │
│  5. Recurse (with cycle detection + max_depth)      │
│  6. Assemble FlowDocument                           │
└─────────────────────────────────────────────────────┘
  │                         │
  │ reads from              │ reads from
  ▼                         ▼
┌─────────────────┐  ┌──────────────────────┐
│ ExtractedUnit   │  │ DependencyGraph      │
│ source_code     │  │ dependencies_of      │
│ metadata        │  │ path_between         │
└─────────────────┘  └──────────────────────┘
  │
  ▼
┌─────────────────────────────────────────────────────┐
│ FlowDocument                                        │
│                                                     │
│  Structured output:                                 │
│  • JSON (machine-readable, for retrieval layer)     │
│  • Markdown (human-readable, for documentation)     │
└─────────────────────────────────────────────────────┘

{
  "entry_point": "CheckoutsController#create",
  "route": { "verb": "POST", "path": "/api/checkouts" },
  "max_depth": 5,
  "generated_at": "2026-02-13T10:30:00Z",
  "steps": [
    {
      "unit": "CheckoutsController#create",
      "type": "controller",
      "file_path": "app/controllers/api/checkouts_controller.rb",
      "operations": [
        {
          "type": "call",
          "target": "CheckoutFindOrCreate",
          "method": "call",
          "line": 42
        },
        {
          "type": "async",
          "target": "CheckoutWorker",
          "method": "perform_async",
          "args_hint": ["checkout.id"],
          "line": 45
        },
        {
          "type": "response",
          "status_code": 201,
          "render_method": "render_created",
          "resolved_from": "Rack::Utils::SYMBOL_TO_STATUS_CODE[:created]",
          "line": 48
        }
      ]
    },
    {
      "unit": "CheckoutFindOrCreate",
      "type": "service",
      "file_path": "app/services/checkout_find_or_create.rb",
      "operations": [
        {
          "type": "transaction",
          "receiver": "Checkout",
          "line": 12,
          "nested": [
            {
              "type": "call",
              "target": "cart",
              "method": "lock!",
              "line": 13
            },
            {
              "type": "call",
              "target": "Checkout",
              "method": "find_pending_or_successful",
              "line": 14
            },
            {
              "type": "conditional",
              "kind": "if",
              "condition": "checkout.persisted?",
              "line": 15,
              "then_ops": [
                {
                  "type": "call",
                  "target": "checkout",
                  "method": "touch",
                  "line": 16
                }
              ],
              "else_ops": [
                {
                  "type": "call",
                  "target": "Checkout",
                  "method": "create!",
                  "line": 18
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

## POST /api/checkouts → CheckoutsController#create

### 1. CheckoutsController#create
_app/controllers/api/checkouts_controller.rb_

| # | Operation | Target | Line |
|---|-----------|--------|------|
| 1 | call | CheckoutFindOrCreate.call | 42 |
| 2 | async | CheckoutWorker.perform_async(checkout.id) | 45 |
| 3 | response | 201 Created (via render_created) | 48 |

### 2. CheckoutFindOrCreate
_app/services/checkout_find_or_create.rb_

| # | Operation | Target | Line |
|---|-----------|--------|------|
| 1 | transaction | Checkout.transaction | 12 |
| 1.1 | lock | cart.lock! | 13 |
| 1.2 | call | Checkout.find_pending_or_successful | 14 |
| 1.3 | if checkout.persisted? | | 15 |
| 1.3a | call | checkout.touch | 16 |
| 1.3b | call | Checkout.create! | 18 |

module Woods
  module FlowAnalysis
    class AstParser
      # Parse Ruby source and return a normalized AST.
      #
      # @param source [String] Ruby source code
      # @return [AstNode] Normalized AST root node
      def parse(source)
        if prism_available?
          parse_with_prism(source)
        else
          parse_with_parser_gem(source)
        end
      end

      # Extract a specific method body from source.
      #
      # @param source [String] Ruby source code
      # @param method_name [String] Method to extract
      # @return [AstNode, nil] Method body AST or nil if not found
      def extract_method(source, method_name)
        root = parse(source)
        find_method_def(root, method_name)
      end

      private

      def prism_available?
        defined?(Prism)
      end
    end
  end
end

AstNode = Struct.new(
  :type,       # Symbol: :send, :block, :if, :rescue, :def, :class, etc.
  :children,   # Array<AstNode>: child nodes
  :line,       # Integer: source line number
  :receiver,   # String, nil: method call receiver (for :send)
  :method_name,# String, nil: method name (for :send, :def)
  :arguments,  # Array<String>: argument representations (for :send)
  keyword_init: true
)

module Woods
  module FlowAnalysis
    class OperationExtractor
      # Extract operations from a method body AST.
      #
      # @param method_ast [AstNode] Parsed method body
      # @param context [Hash] Unit metadata for resolving receivers
      # @return [Array<Hash>] Ordered operations
      def extract(method_ast, context: {})
        operations = []
        walk(method_ast, operations, context)
        operations
      end

      private

      def walk(node, operations, context)
        case node.type
        when :send
          handle_send(node, operations, context)
        when :block
          handle_block(node, operations, context)
        when :if
          handle_conditional(node, operations, context)
        when :rescue
          handle_rescue(node, operations, context)
        else
          # Recurse into children
          node.children&.each { |child| walk(child, operations, context) if child.is_a?(AstNode) }
        end
      end

      def handle_send(node, operations, context)
        if transaction_call?(node)
          # Handled by handle_block when we see the block wrapper
          return
        end

        if async_enqueue?(node)
          operations << {
            type: :async,
            target: node.receiver,
            method: node.method_name,
            args_hint: extract_args_hint(node),
            line: node.line
          }
        elsif response_call?(node)
          operations << {
            type: :response,
            status_code: ResponseCodeMapper.resolve(node),
            render_method: node.method_name,
            line: node.line
          }
        elsif significant_call?(node, context)
          operations << {
            type: :call,
            target: node.receiver,
            method: node.method_name,
            line: node.line
          }
        end
      end

      def handle_block(node, operations, context)
        send_node = node.children.first
        if transaction_call?(send_node)
          nested = []
          walk_block_body(node, nested, context)

          operations << {
            type: :transaction,
            receiver: send_node.receiver,
            line: send_node.line,
            nested: nested
          }
        else
          # Non-transaction block — recurse into body
          walk_block_body(node, operations, context)
        end
      end

      def handle_conditional(node, operations, context)
        then_ops = []
        else_ops = []

        walk(node.children[1], then_ops, context) if node.children[1]
        walk(node.children[2], else_ops, context) if node.children[2]

        # Only emit if at least one branch has significant operations
        return if then_ops.empty? && else_ops.empty?

        operations << {
          type: :conditional,
          kind: node.type == :if ? "if" : "unless",
          condition: node.children[0].to_source,
          line: node.line,
          then_ops: then_ops,
          else_ops: else_ops
        }
      end

      # Detects: .transaction, .with_lock
      def transaction_call?(node)
        node.type == :send &&
          %w[transaction with_lock].include?(node.method_name)
      end

      # Detects: perform_async, perform_later, perform_in, perform_at
      def async_enqueue?(node)
        node.type == :send &&
          %w[perform_async perform_later perform_in perform_at].include?(node.method_name)
      end

      # Detects: render, redirect_to, head, render_*, respond_with
      def response_call?(node)
        node.type == :send &&
          (node.method_name.start_with?("render") ||
           %w[redirect_to head respond_with].include?(node.method_name))
      end
    end
  end
end

module Woods
  module FlowAnalysis
    class ResponseCodeMapper
      SYMBOL_TO_STATUS = Rack::Utils::SYMBOL_TO_STATUS_CODE

      # Resolve a render/response AST node to an HTTP status code.
      #
      # @param node [AstNode] A :send node for a render/redirect call
      # @return [Integer, nil] HTTP status code or nil if unresolvable
      def self.resolve(node)
        # Case 1: render json: ..., status: :created
        status_arg = extract_status_kwarg(node)
        return resolve_status(status_arg) if status_arg

        # Case 2: render_created (convention: render_<status>)
        if node.method_name.start_with?("render_")
          status_name = node.method_name.delete_prefix("render_")
          return SYMBOL_TO_STATUS[status_name.to_sym] if SYMBOL_TO_STATUS.key?(status_name.to_sym)
        end

        # Case 3: head :no_content
        if node.method_name == "head" && node.arguments.first
          return resolve_status(node.arguments.first)
        end

        # Case 4: redirect_to (default 302)
        return 302 if node.method_name == "redirect_to"

        nil
      end

      def self.resolve_status(value)
        case value
        when Integer then value
        when Symbol  then SYMBOL_TO_STATUS[value]
        when String
          # Try as symbol first, then as integer
          SYMBOL_TO_STATUS[value.to_sym] || (value.match?(/\A\d+\z/) ? value.to_i : nil)
        end
      end
    end
  end
end

# In Retrieval::StrategySelector (future)
when :trace
  if entry_point = resolve_entry_point(classification)
    # Delegate to FlowAssembler for ordered trace
    flow = FlowAssembler.new(graph: graph, extracted_dir: output_dir).assemble(entry_point)
    flow.to_context  # Returns token-budgeted context string
  else
    # Fall back to graph_traversal + vector_search
    HybridSearch.new(...)
  end

# lib/tasks/flow.rake
namespace :woods do
  desc "Generate execution flow document for an entry point"
  task :flow, [:entry_point] => :environment do |_t, args|
    require "woods"

    entry_point = args[:entry_point]
    abort "Usage: rake woods:flow[CheckoutsController#create]" unless entry_point

    # Load extracted data from JSON files on disk
    output_dir = Woods.configuration.output_dir
    graph = Woods::DependencyGraph.load(File.join(output_dir, "dependency_graph.json"))

    assembler = Woods::FlowAssembler.new(graph: graph, extracted_dir: output_dir)
    flow = assembler.assemble(entry_point)

    case ENV.fetch("FORMAT", "markdown")
    when "json"
      puts JSON.pretty_generate(flow.to_h)
    when "markdown"
      puts flow.to_markdown
    end
  end
end

# Markdown output (default)
bundle exec rake woods:flow[CheckoutsController#create]

# JSON output
FORMAT=json bundle exec rake woods:flow[CheckoutsController#create]

# With depth limit
MAX_DEPTH=3 bundle exec rake woods:flow[CheckoutsController#create]

status = checkout.persisted? ? :ok : :created
render json: checkout, status: status

RSpec.describe Woods::FlowAnalysis::OperationExtractor do
  describe "#extract" do
    it "extracts method calls in source order" do
      source = <<~RUBY
        def create
          result = FindOrCreate.call(cart)
          Worker.perform_async(result.id)
          render_created(result)
        end
      RUBY

      ast = AstParser.new.extract_method(source, "create")
      ops = described_class.new.extract(ast)

      expect(ops.map { |o| o[:type] }).to eq(%i[call async response])
      expect(ops[0][:target]).to eq("FindOrCreate")
      expect(ops[1][:target]).to eq("Worker")
      expect(ops[2][:status_code]).to eq(201)
    end

    it "extracts transaction blocks with exact receiver" do
      source = <<~RUBY
        def call
          Checkout.transaction do
            cart.lock!
            checkout = Checkout.find_or_create_by!(cart: cart)
          end
        end
      RUBY

      ast = AstParser.new.extract_method(source, "call")
      ops = described_class.new.extract(ast)

      expect(ops.size).to eq(1)
      expect(ops[0][:type]).to eq(:transaction)
      expect(ops[0][:receiver]).to eq("Checkout")
      expect(ops[0][:nested].size).to eq(2)
    end

    it "handles cycles without infinite recursion" do
      # Test via FlowAssembler with a graph where A → B → A
    end
  end
end