woods 1.0.0

data/lib/woods/ruby_analyzer/dataflow_analyzer.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative '../ast/parser'
+require_relative '../ast/call_site_extractor'
+
+module Woods
+  module RubyAnalyzer
+    # Annotates existing ExtractedUnit objects with data transformation metadata.
+    #
+    # Conservative v1: detects common data transformation patterns by scanning
+    # for specific method calls that indicate construction, serialization, or
+    # deserialization.
+    #
+    # @example
+    #   analyzer = RubyAnalyzer::DataFlowAnalyzer.new
+    #   analyzer.annotate(units)
+    #   units.first.metadata[:data_transformations]
+    #   #=> [{ method: "to_json", category: :serialization, line: 5 }]
+    #
+    class DataFlowAnalyzer
+      CONSTRUCTION_METHODS = %w[new].freeze
+      SERIALIZATION_METHODS = %w[to_h to_json to_a serialize as_json].freeze
+      DESERIALIZATION_METHODS = %w[from_json parse].freeze
+      CATEGORY_BY_METHOD = [
+        *CONSTRUCTION_METHODS.map { |m| [m, :construction] },
+        *SERIALIZATION_METHODS.map { |m| [m, :serialization] },
+        *DESERIALIZATION_METHODS.map { |m| [m, :deserialization] }
+      ].to_h.freeze
+
+      # @param parser [Ast::Parser, nil] Parser instance (creates default if nil)
+      def initialize(parser: nil)
+        @parser = parser || Ast::Parser.new
+        @call_site_extractor = Ast::CallSiteExtractor.new
+      end
+
+      # Annotate units with data transformation metadata.
+      #
+      # Mutates each unit's metadata hash by adding a :data_transformations key.
+      #
+      # @param units [Array<ExtractedUnit>] Units to annotate
+      # @return [Array<ExtractedUnit>] The same units, now annotated
+      def annotate(units)
+        units.each do |unit|
+          next unless unit.source_code
+
+          transformations = detect_transformations(unit.source_code)
+          unit.metadata[:data_transformations] = transformations
+        end
+      end
+
+      private
+
+      def detect_transformations(source)
+        root = @parser.parse(source)
+        calls = @call_site_extractor.extract(root)
+
+        calls.filter_map do |call|
+          category = categorize(call[:method_name])
+          next unless category
+
+          {
+            method: call[:method_name],
+            category: category,
+            receiver: call[:receiver],
+            line: call[:line]
+          }
+        end
+      rescue Woods::ExtractionError
+        []
+      end
+
+      def categorize(method_name)
+        CATEGORY_BY_METHOD[method_name]
+      end
+    end
+  end
+end

data/lib/woods/ruby_analyzer/fqn_builder.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Woods
+  module RubyAnalyzer
+    # Shared helper for building fully qualified names from a name and namespace stack.
+    module FqnBuilder
+      private
+
+      def build_fqn(name, namespace_stack)
+        if namespace_stack.empty?
+          name
+        else
+          "#{namespace_stack.join('::')}::#{name}"
+        end
+      end
+    end
+  end
+end

data/lib/woods/ruby_analyzer/mermaid_renderer.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Woods
+  module RubyAnalyzer
+    # Renders Mermaid-format diagrams from extracted units, dependency graphs,
+    # and graph analysis data.
+    #
+    # Produces valid Mermaid markdown strings for call graphs, dependency maps,
+    # dataflow charts, and combined architecture documents.
+    #
+    # @example Rendering a call graph
+    #   renderer = MermaidRenderer.new
+    #   units = RubyAnalyzer.analyze(paths: ["lib/"])
+    #   puts renderer.render_call_graph(units)
+    #
+    class MermaidRenderer
+      # Render a call graph from extracted units showing method call relationships.
+      #
+      # Each unit with dependencies produces edges to its targets. Nodes are
+      # styled by type (class, module, method).
+      #
+      # @param units [Array<ExtractedUnit>] Units to render
+      # @return [String] Mermaid graph TD markdown
+      def render_call_graph(units)
+        lines = ['graph TD']
+        return lines.join("\n") if units.nil? || units.empty?
+
+        seen_nodes = Set.new
+        seen_edges = Set.new
+
+        units.each do |unit|
+          node_id = sanitize_id(unit.identifier)
+          lines << "  #{node_id}[\"#{escape_label(unit.identifier)}\"]" if seen_nodes.add?(node_id)
+
+          (unit.dependencies || []).each do |dep|
+            target = dep[:target] || dep['target']
+            next unless target
+
+            target_id = sanitize_id(target)
+            lines << "  #{target_id}[\"#{escape_label(target)}\"]" if seen_nodes.add?(target_id)
+
+            via = dep[:via] || dep['via']
+            edge_key = "#{node_id}->#{target_id}"
+            next unless seen_edges.add?(edge_key)
+
+            lines << if via
+                       "  #{node_id} -->|#{via}| #{target_id}"
+                     else
+                       "  #{node_id} --> #{target_id}"
+                     end
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      # Render a dependency map from graph data (as returned by DependencyGraph#to_h).
+      #
+      # Shows nodes grouped by type with edges representing dependencies.
+      #
+      # @param graph_data [Hash] Serialized graph data with :nodes and :edges keys
+      # @return [String] Mermaid graph TD markdown
+      def render_dependency_map(graph_data)
+        lines = ['graph TD']
+        return lines.join("\n") unless graph_data
+
+        nodes = graph_data[:nodes] || graph_data['nodes'] || {}
+        edges = graph_data[:edges] || graph_data['edges'] || {}
+
+        return lines.join("\n") if nodes.empty?
+
+        # Group nodes by type for subgraph rendering
+        by_type = {}
+        nodes.each do |identifier, meta|
+          type = (meta[:type] || meta['type'])&.to_sym || :unknown
+          by_type[type] ||= []
+          by_type[type] << identifier
+        end
+
+        # Render subgraphs per type
+        by_type.each do |type, identifiers|
+          lines << "  subgraph #{type}"
+          identifiers.each do |id|
+            node_id = sanitize_id(id)
+            lines << "    #{node_id}[\"#{escape_label(id)}\"]"
+          end
+          lines << '  end'
+        end
+
+        # Render edges
+        seen_edges = Set.new
+        edges.each do |source, targets|
+          Array(targets).each do |target|
+            next unless nodes.key?(target)
+
+            edge_key = "#{sanitize_id(source)}->#{sanitize_id(target)}"
+            next unless seen_edges.add?(edge_key)
+
+            lines << "  #{sanitize_id(source)} --> #{sanitize_id(target)}"
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      # Render a dataflow diagram from units that have data_transformations metadata.
+      #
+      # Shows transformation chains: which units construct, serialize, or
+      # deserialize data, with edges flowing between them.
+      #
+      # @param units [Array<ExtractedUnit>] Units with :data_transformations metadata
+      # @return [String] Mermaid flowchart TD markdown
+      def render_dataflow(units)
+        lines = ['flowchart TD']
+        return lines.join("\n") if units.nil? || units.empty?
+
+        seen_nodes = Set.new
+
+        units.each do |unit|
+          transformations = unit.metadata[:data_transformations] || unit.metadata['data_transformations']
+          next unless transformations.is_a?(Array) && transformations.any?
+
+          node_id = sanitize_id(unit.identifier)
+          if seen_nodes.add?(node_id)
+            shape = dataflow_shape(transformations)
+            lines << "  #{node_id}#{shape}"
+          end
+
+          transformations.each do |t|
+            receiver = t[:receiver] || t['receiver']
+            next unless receiver
+
+            receiver_id = sanitize_id(receiver)
+            category = (t[:category] || t['category'])&.to_s
+            method_name = t[:method] || t['method']
+
+            lines << "  #{receiver_id}[\"#{escape_label(receiver)}\"]" if seen_nodes.add?(receiver_id)
+
+            label = [category, method_name].compact.join(': ')
+            lines << "  #{node_id} -->|#{label}| #{receiver_id}"
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      # Render a combined architecture document with all three diagram types.
+      #
+      # Returns a markdown document with headers and fenced Mermaid code blocks
+      # for call graph, dependency map, and dataflow diagrams, plus a summary
+      # of graph analysis findings.
+      #
+      # @param units [Array<ExtractedUnit>] Extracted units
+      # @param graph_data [Hash] Serialized dependency graph data
+      # @param analysis [Hash] Graph analysis report from GraphAnalyzer#analyze
+      # @return [String] Combined markdown document
+      def render_architecture(units, graph_data, analysis)
+        sections = []
+
+        sections << '# Architecture Overview'
+        sections << ''
+
+        # Call graph
+        sections << '## Call Graph'
+        sections << ''
+        sections << '```mermaid'
+        sections << render_call_graph(units)
+        sections << '```'
+        sections << ''
+
+        # Dependency map
+        sections << '## Dependency Map'
+        sections << ''
+        sections << '```mermaid'
+        sections << render_dependency_map(graph_data)
+        sections << '```'
+        sections << ''
+
+        # Dataflow
+        sections << '## Data Flow'
+        sections << ''
+        sections << '```mermaid'
+        sections << render_dataflow(units)
+        sections << '```'
+        sections << ''
+
+        # Analysis summary
+        sections << '## Analysis Summary'
+        sections << ''
+        sections.concat(render_stats_section(analysis))
+
+        sections.join("\n")
+      end
+
+      private
+
+      # Render the Analysis Summary section lines for a given analysis hash.
+      #
+      # @param analysis [Hash, nil] Graph analysis report from GraphAnalyzer#analyze
+      # @return [Array<String>] Lines to append to the architecture document
+      def render_stats_section(analysis)
+        lines = []
+        return lines unless analysis
+
+        stats = analysis[:stats] || analysis['stats'] || {}
+        lines << "- **Orphans:** #{stats[:orphan_count] || stats['orphan_count'] || 0}"
+        lines << "- **Dead ends:** #{stats[:dead_end_count] || stats['dead_end_count'] || 0}"
+        lines << "- **Hubs:** #{stats[:hub_count] || stats['hub_count'] || 0}"
+        lines << "- **Cycles:** #{stats[:cycle_count] || stats['cycle_count'] || 0}"
+
+        hubs = analysis[:hubs] || analysis['hubs'] || []
+        lines.concat(render_hubs_section(hubs))
+
+        cycles = analysis[:cycles] || analysis['cycles'] || []
+        if cycles.any?
+          lines << ''
+          lines << '### Cycles'
+          lines << ''
+          cycles.each { |cycle| lines << "- #{cycle.join(' -> ')}" }
+        end
+
+        lines
+      end
+
+      # Render the Top Hubs subsection lines.
+      #
+      # @param hubs [Array<Hash>] Hub entries with :identifier and :dependent_count keys
+      # @return [Array<String>] Lines to append, or empty array if no hubs
+      def render_hubs_section(hubs)
+        return [] unless hubs.any?
+
+        lines = ['', '### Top Hubs', '']
+        hubs.first(5).each do |hub|
+          id = hub[:identifier] || hub['identifier']
+          count = hub[:dependent_count] || hub['dependent_count']
+          lines << "- #{id} (#{count} dependents)"
+        end
+        lines
+      end
+
+      # Sanitize an identifier for use as a Mermaid node ID.
+      #
+      # Replaces characters that Mermaid cannot use in node IDs with underscores.
+      #
+      # @param identifier [String] Raw identifier
+      # @return [String] Safe Mermaid node ID
+      def sanitize_id(identifier)
+        identifier.to_s.gsub(/[^a-zA-Z0-9_]/, '_')
+      end
+
+      # Escape a label string for use inside Mermaid quoted labels.
+      #
+      # @param label [String] Raw label text
+      # @return [String] Escaped label
+      def escape_label(label)
+        label.to_s.gsub('"', '&quot;')
+      end
+
+      # Determine Mermaid node shape based on dominant transformation category.
+      #
+      # @param transformations [Array<Hash>] Transformation metadata
+      # @return [String] Mermaid shape syntax
+      def dataflow_shape(transformations)
+        categories = transformations.map { |t| (t[:category] || t['category'])&.to_sym }
+
+        if categories.include?(:construction)
+          "([\"#{escape_label(transformations.first[:method] || 'new')}\"])"
+        elsif categories.include?(:serialization)
+          '[/"serialization"/]'
+        elsif categories.include?(:deserialization)
+          '[\"deserialization"\\]'
+        else
+          '["data"]'
+        end
+      end
+    end
+  end
+end

data/lib/woods/ruby_analyzer/method_analyzer.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require_relative '../ast/parser'
+require_relative '../ast/method_extractor'
+require_relative '../ast/call_site_extractor'
+require_relative '../extracted_unit'
+require_relative 'fqn_builder'
+
+module Woods
+  module RubyAnalyzer
+    # Extracts method-level units from Ruby source code.
+    #
+    # For each class/module, extracts methods as ExtractedUnit objects with type
+    # :ruby_method. Includes visibility, parameters, call graph, and dependencies.
+    #
+    # @example
+    #   analyzer = RubyAnalyzer::MethodAnalyzer.new
+    #   units = analyzer.analyze(source: File.read(path), file_path: path)
+    #   units.first.identifier #=> "MyClass#my_method"
+    #
+    class MethodAnalyzer
+      include FqnBuilder
+
+      # @param parser [Ast::Parser, nil] Parser instance (creates default if nil)
+      def initialize(parser: nil)
+        @parser = parser || Ast::Parser.new
+        @call_site_extractor = Ast::CallSiteExtractor.new
+      end
+
+      # Analyze source code and extract method units.
+      #
+      # @param source [String] Ruby source code
+      # @param file_path [String] Absolute path to the source file
+      # @return [Array<ExtractedUnit>] Extracted method units
+      def analyze(source:, file_path:)
+        root = @parser.parse(source)
+        units = []
+        extract_methods_from_tree(root, source, file_path, [], units)
+        units
+      end
+
+      private
+
+      def extract_methods_from_tree(node, source, file_path, namespace_stack, units)
+        return unless node.is_a?(Ast::Node)
+
+        case node.type
+        when :class
+          process_container_methods(node, :class, source, file_path, namespace_stack, units)
+        when :module
+          process_container_methods(node, :module, source, file_path, namespace_stack, units)
+        else
+          (node.children || []).each do |child|
+            extract_methods_from_tree(child, source, file_path, namespace_stack, units)
+          end
+        end
+      end
+
+      def process_container_methods(node, type, source, file_path, namespace_stack, units)
+        name = node.method_name
+        fqn = build_fqn(name, namespace_stack)
+        body_offset = type == :class ? 2 : 1
+        body_children = (node.children || [])[body_offset..] || []
+
+        visibility_tracker = VisibilityTracker.new
+        inner_ns = namespace_stack + [name]
+
+        body_children.each do |child|
+          next unless child.is_a?(Ast::Node)
+
+          case child.type
+          when :send
+            visibility_tracker.process_send(child)
+          when :def
+            units << build_method_unit(child, fqn, '#', visibility_tracker.current, file_path)
+          when :defs
+            units << build_method_unit(child, fqn, '.', :public, file_path)
+          when :class, :module
+            extract_methods_from_tree(child, source, file_path, inner_ns, units)
+          end
+        end
+      end
+
+      def build_method_unit(method_node, class_fqn, separator, visibility, file_path)
+        identifier = "#{class_fqn}#{separator}#{method_node.method_name}"
+        call_graph = extract_call_graph(method_node)
+        dependencies = build_dependencies(call_graph)
+        unit = ExtractedUnit.new(type: :ruby_method, identifier: identifier, file_path: file_path)
+        unit.namespace = class_fqn
+        unit.source_code = method_node.source
+        unit.metadata = {
+          visibility: visibility,
+          call_graph: call_graph
+        }
+        unit.dependencies = dependencies
+        unit
+      end
+
+      def extract_call_graph(method_node)
+        calls = @call_site_extractor.extract(method_node)
+        calls.filter_map do |call|
+          next unless call[:receiver]
+          # Only include calls with a capitalized receiver (likely a class/constant)
+          next unless call[:receiver].match?(/\A[A-Z]/)
+
+          {
+            target: call[:receiver],
+            method: call[:method_name],
+            line: call[:line]
+          }
+        end
+      end
+
+      def build_dependencies(call_graph)
+        call_graph.map { |c| c[:target] }.uniq.map do |target|
+          { type: :ruby_class, target: target, via: :method_call }
+        end
+      end
+
+      # Tracks visibility state as we walk through class body statements.
+      class VisibilityTracker
+        VISIBILITY_METHODS = %w[private protected public].freeze
+
+        attr_reader :current
+
+        def initialize
+          @current = :public
+        end
+
+        # Process a send node that might be a visibility modifier.
+        def process_send(send_node)
+          return unless send_node.method_name
+          return unless VISIBILITY_METHODS.include?(send_node.method_name)
+          # Only bare calls (no receiver, no arguments) act as section modifiers
+          return if send_node.receiver
+          return if send_node.arguments && !send_node.arguments.empty?
+
+          @current = send_node.method_name.to_sym
+        end
+      end
+    end
+  end
+end

data/lib/woods/ruby_analyzer/trace_enricher.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require_relative '../extracted_unit'
+
+module Woods
+  module RubyAnalyzer
+    # Enriches ExtractedUnit objects with runtime trace data.
+    #
+    # Two modes:
+    # - Recording: wraps a block with TracePoint to capture method calls
+    # - Merging: enriches existing units with previously collected trace data
+    #
+    # @example Recording
+    #   trace_data = TraceEnricher.record { MyApp.run }
+    #
+    # @example Merging
+    #   TraceEnricher.merge(units: units, trace_data: trace_data)
+    #
+    class TraceEnricher
+      # Record method calls during block execution using TracePoint.
+      #
+      # @yield Block to trace
+      # @return [Array<Hash>] Collected trace events
+      def self.record(&block)
+        traces = []
+
+        trace = TracePoint.new(:call, :return) do |tp|
+          traces << {
+            class_name: tp.defined_class&.name || tp.defined_class.to_s,
+            method_name: tp.method_id.to_s,
+            event: tp.event.to_s,
+            path: tp.path,
+            line: tp.lineno,
+            caller_class: extract_caller_class(tp),
+            caller_method: extract_caller_method(tp),
+            return_class: tp.event == :return ? safe_return_class(tp) : nil
+          }
+        end
+
+        trace.enable(&block)
+        traces
+      end
+
+      # Merge trace data into existing units.
+      #
+      # Mutates each matching unit's metadata by adding a :trace key with
+      # call count, callers, and return types.
+      #
+      # @param units [Array<ExtractedUnit>] Units to enrich
+      # @param trace_data [Array<Hash>] Trace events (from recording or JSON fixture)
+      # @return [Array<ExtractedUnit>] The same units, now enriched
+      def self.merge(units:, trace_data:)
+        return units if trace_data.nil? || trace_data.empty?
+
+        # Index traces by class_name + method_name
+        grouped = group_traces(trace_data)
+
+        units.each do |unit|
+          class_name, method_name = parse_identifier(unit.identifier)
+          next unless class_name && method_name
+
+          key = "#{class_name}##{method_name}"
+          next unless grouped.key?(key)
+
+          traces = grouped[key]
+
+          calls = traces.select { |t| fetch_key(t, :event) == 'call' }
+          returns = traces.select { |t| fetch_key(t, :event) == 'return' }
+
+          callers = calls.filter_map do |t|
+            caller_class = fetch_key(t, :caller_class)
+            caller_method = fetch_key(t, :caller_method)
+            next unless caller_class
+
+            { 'caller_class' => caller_class, 'caller_method' => caller_method }
+          end
+
+          return_types = returns.filter_map do |t|
+            fetch_key(t, :return_class)
+          end.uniq
+
+          unit.metadata[:trace] = {
+            call_count: calls.size,
+            callers: callers,
+            return_types: return_types
+          }
+        end
+      end
+
+      class << self
+        private
+
+        def fetch_key(hash, key)
+          hash[key.to_s] || hash[key.to_sym]
+        end
+
+        def group_traces(trace_data)
+          grouped = Hash.new { |h, k| h[k] = [] }
+          trace_data.each do |trace|
+            class_name = fetch_key(trace, :class_name)
+            method_name = fetch_key(trace, :method_name)
+            next unless class_name && method_name
+
+            key = "#{class_name}##{method_name}"
+            grouped[key] << trace
+          end
+          grouped
+        end
+
+        def parse_identifier(identifier)
+          # Handle both "Class#method" and "Class.method" formats
+          if identifier.include?('#')
+            identifier.split('#', 2)
+          elsif identifier.include?('.')
+            identifier.split('.', 2)
+          end
+        end
+
+        def extract_caller_class(tp)
+          binding_obj = tp.binding
+          receiver = binding_obj.receiver
+          receiver.is_a?(Class) || receiver.is_a?(Module) ? receiver.name : receiver.class.name
+        rescue StandardError
+          nil
+        end
+
+        def extract_caller_method(_tp)
+          # TracePoint doesn't directly expose caller method,
+          # but we can get it from the call stack
+          caller_locations(3, 1)&.first&.label
+        rescue StandardError
+          nil
+        end
+
+        def safe_return_class(tp)
+          tp.return_value.class.name
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end