markdown-run 0.1.11 → 0.2.0

data/lib/pg_flamegraph_svg.rb

@@ -0,0 +1,221 @@
+require 'json'
+require 'securerandom'
+
+class PostgreSQLFlameGraphSVG
+  def initialize(explain_json, width = 1200, height = 600)
+    @explain_data = JSON.parse(explain_json)
+    @width = width
+    @height = height
+    @font_size = 20
+    @min_width = 1
+    @colors = [
+      '#e74c3c', '#3498db', '#2ecc71', '#f39c12', '#9b59b6',
+      '#1abc9c', '#e67e22', '#95a5a6', '#34495e', '#e91e63'
+    ]
+  end
+
+  def generate_svg
+    plan = @explain_data[0]['Plan']
+
+    # Calculate the layout
+    flamegraph_data = build_flamegraph_data(plan)
+
+    # Generate SVG
+    generate_svg_content(flamegraph_data)
+  end
+
+  private
+
+  def build_flamegraph_data(plan, depth = 0, start_time = 0)
+    node_name = format_node_name(plan)
+    actual_time = plan['Actual Total Time'] || 0
+
+    # Create the current node
+    current_node = {
+      name: node_name,
+      time: actual_time,
+      depth: depth,
+      start: start_time,
+      children: []
+    }
+
+    # Process children
+    if plan['Plans']
+      child_start = start_time
+      plan['Plans'].each do |child_plan|
+        child_node = build_flamegraph_data(child_plan, depth + 1, child_start)
+        current_node[:children] << child_node
+        child_start += child_node[:time]
+      end
+    end
+
+    current_node
+  end
+
+  def format_node_name(node)
+    node_type = node['Node Type']
+
+    # Add relevant details
+    details = []
+
+    if node['Relation Name']
+      details << node['Relation Name']
+    end
+
+    if node['Index Name']
+      details << "idx:#{node['Index Name']}"
+    end
+
+    if node['Join Type']
+      details << node['Join Type']
+    end
+
+    # Build the final name
+    name = node_type
+    unless details.empty?
+      name += " (#{details.join(', ')})"
+    end
+
+    # Add timing info
+    if node['Actual Total Time']
+      name += " [#{node['Actual Total Time'].round(2)}ms]"
+    end
+
+    name
+  end
+
+  def generate_svg_content(flamegraph_data)
+    max_depth = calculate_max_depth(flamegraph_data)
+    total_time = flamegraph_data[:time]
+
+    svg_height = (max_depth + 1) * (@font_size + 4) + 80
+
+    svg = <<~SVG
+      <?xml version="1.0" encoding="UTF-8"?>
+      <svg width="#{@width}" height="#{svg_height}" xmlns="http://www.w3.org/2000/svg">
+        <style>
+          .frame { stroke: white; stroke-width: 1; cursor: pointer; }
+          .frame:hover { stroke: black; stroke-width: 2; }
+          .frame-text { font-family: monospace; font-size: #{@font_size}px; fill: white; pointer-events: none; }
+          .title { font-family: Arial; font-size: 16px; font-weight: bold; fill: #333; }
+          .subtitle { font-family: Arial; font-size: 12px; fill: #666; }
+        </style>
+
+        <!-- Title -->
+        <text x="#{@width/2}" y="20" class="title" text-anchor="middle">PostgreSQL Query Execution Plan Flamegraph</text>
+        <text x="#{@width/2}" y="35" class="subtitle" text-anchor="middle">Total Execution Time: #{total_time.round(2)}ms</text>
+
+        <!-- Flamegraph -->
+        <g transform="translate(0, 45)">
+    SVG
+
+    # Generate rectangles recursively
+    svg += generate_rectangles(flamegraph_data, total_time, 0)
+
+    svg += <<~SVG
+        </g>
+      </svg>
+    SVG
+
+    svg
+  end
+
+  def generate_rectangles(node, total_time, y_offset)
+    return "" if node[:time] <= 0
+
+    # Calculate dimensions
+    width_ratio = node[:time] / total_time
+    rect_width = [@width * width_ratio, @min_width].max
+    rect_height = @font_size + 4
+
+    x_position = (node[:start] / total_time) * @width
+    y_position = y_offset
+
+    # Choose color based on node type
+    color = get_node_color(node[:name])
+
+    # Generate rectangle and text
+    svg = <<~SVG
+      <rect class="frame"
+            x="#{x_position}"
+            y="#{y_position}"
+            width="#{rect_width}"
+            height="#{rect_height}"
+            fill="#{color}">
+        <title>#{escape_xml(node[:name])}
+Time: #{node[:time].round(2)}ms
+Percentage: #{((node[:time] / total_time) * 100).round(1)}%</title>
+      </rect>
+    SVG
+
+    # Add text if rectangle is wide enough
+    if rect_width > 50
+      text_x = x_position + 4
+      text_y = y_position + @font_size + 1
+
+      # Truncate text if necessary
+      display_text = truncate_text(node[:name], rect_width - 8)
+
+      svg += <<~SVG
+        <text class="frame-text" x="#{text_x}" y="#{text_y}">#{escape_xml(display_text)}</text>
+      SVG
+    end
+
+    # Generate children
+    child_y = y_position + rect_height + 2
+    node[:children].each do |child|
+      svg += generate_rectangles(child, total_time, child_y)
+    end
+
+    svg
+  end
+
+  def calculate_max_depth(node, current_depth = 0)
+    max_child_depth = current_depth
+
+    node[:children].each do |child|
+      child_depth = calculate_max_depth(child, current_depth + 1)
+      max_child_depth = [max_child_depth, child_depth].max
+    end
+
+    max_child_depth
+  end
+
+  def get_node_color(node_name)
+    # Color code by operation type
+    case node_name
+    when /Seq Scan/
+      '#e74c3c'  # Red - potentially slow
+    when /Index.*Scan/
+      '#2ecc71'  # Green - good
+    when /Hash Join|Nested Loop|Merge Join/
+      '#3498db'  # Blue - joins
+    when /Sort|Aggregate/
+      '#f39c12'  # Orange - processing
+    when /Result/
+      '#95a5a6'  # Gray - simple
+    else
+      # Cycle through colors based on hash
+      @colors[node_name.hash.abs % @colors.length]
+    end
+  end
+
+  def truncate_text(text, max_width)
+    # Rough estimate: 1 character ≈ 7 pixels in monospace
+    max_chars = (max_width / 7).to_i
+
+    if text.length <= max_chars
+      text
+    else
+      text[0, max_chars - 3] + "..."
+    end
+  end
+
+  def escape_xml(text)
+    text.gsub('&', '&amp;')
+        .gsub('<', '&lt;')
+        .gsub('>', '&gt;')
+        .gsub('"', '&quot;')
+        .gsub("'", '&#39;')
+  end
+end

data/lib/postgres_helper.rb

@@ -0,0 +1,94 @@
+require_relative "test_silencer"
+
+module PostgresHelper
+  class << self
+    def psql_command
+      @psql_command ||= detect_psql_command
+    end
+
+    def available?
+      return false if psql_command.nil?
+
+      # If using Docker, check required env vars are present
+      if using_docker?
+        has_required_env_vars?
+      else
+        true
+      end
+    end
+
+    def using_docker?
+      cmd = psql_command
+      cmd && cmd.start_with?("docker exec")
+    end
+
+    # Reset cached command detection (for tests)
+    def reset_cache!
+      @psql_command = nil
+    end
+
+    def validate_env_vars!
+      return unless using_docker?
+
+      required_vars = ["PGUSER", "PGDATABASE"]
+      missing_vars = required_vars.reject { |var| ENV[var] }
+
+      if missing_vars.any?
+        TestSilencer.abort_unless_testing "Error: PostgreSQL is running in Docker but required environment variables are missing: #{missing_vars.join(", ")}. Please set these variables before running psql commands."
+      end
+    end
+
+    private
+
+    def has_required_env_vars?
+      required_vars = ["PGUSER", "PGDATABASE"]
+      required_vars.all? { |var| ENV[var] }
+    end
+
+    def detect_psql_command
+      # Check if psql is available locally
+      return "psql" if system("command -v psql > /dev/null 2>&1")
+
+      # Check if docker is available
+      return nil unless system("command -v docker > /dev/null 2>&1")
+
+      # Find running postgres container
+      container_id = find_postgres_container
+      return nil if container_id.nil? || container_id.empty?
+
+      # Build docker exec command with environment variables passed through
+      env_vars = build_env_vars
+      "docker exec -i -u postgres #{env_vars}#{container_id} psql"
+    end
+
+    def build_env_vars
+      # Pass through PostgreSQL environment variables if they exist
+      pg_env_vars = [ "PGUSER", "PGPASSWORD", "PGDATABASE", "PGHOST", "PGPORT" ]
+      env_flags = pg_env_vars.map do |var|
+        value = ENV[var]
+        "-e #{var}=\"#{value}\" " if value
+      end.compact.join
+      env_flags.empty? ? "" : "#{env_flags} "
+    end
+
+    def find_postgres_container
+      # Try to find a running postgres container
+      # First, check for container with postgres in the name
+      output = `docker ps --filter "ancestor=postgres" --format "{{.ID}}" 2>/dev/null`.strip
+      return output.split("\n").first unless output.empty?
+
+      # Alternative: check for containers with "postgres" in name
+      output = `docker ps --filter "name=postgres" --format "{{.ID}}" 2>/dev/null`.strip
+      return output.split("\n").first unless output.empty?
+
+      # Last resort: check if any running container has psql command
+      containers = `docker ps --format "{{.ID}}" 2>/dev/null`.strip.split("\n")
+      containers.each do |container_id|
+        has_psql = system("docker exec #{container_id} which psql > /dev/null 2>&1")
+        return container_id if has_psql
+      end
+
+      nil
+    end
+  end
+end

data/lib/result_helper.rb

@@ -1,4 +1,9 @@
+require_relative "flamegraph_helper"
+require_relative "test_silencer"
+
 module ResultHelper
+  include FlamegraphHelper
+
   private
 
   def ruby_style_result?(lang)
@@ -12,7 +17,7 @@ module ResultHelper
   end
 
   def result_block_header(lang)
-    ruby_style_result?(lang) ? "```ruby RESULT\n" : "```RESULT\n"
+    ruby_style_result?(lang) ? "```ruby\n" : "``` {result}\n"
   end
 
   def result_block_regex(lang)
@@ -20,14 +25,21 @@ module ResultHelper
       # For mermaid, look for existing image tags with .svg extension
       /^!\[.*\]\(.*\.svg\)$/i
     elsif ruby_style_result?(lang)
+      # For ruby, check for old-style ```ruby RESULT blocks (for backward compatibility during migration)
       /^```ruby\s+RESULT$/i
     else
-      /^```RESULT$/i
+      /^```\s*\{result\}$/i
     end
   end
 
-  def add_result_block(result_output, blank_line_before_new_result)
-    if mermaid_style_result?(@current_block_lang)
+  def add_result_block(result_output, blank_line_before_new_result, closing_line = nil)
+    if ruby_style_result?(@current_block_lang)
+      # For ruby, replace the code block content with xmpfilter output
+      @output_lines << result_output
+      @output_lines << "\n" unless result_output.empty? || result_output.end_with?("\n")
+      @output_lines << (closing_line || "```\n")
+      @output_lines << "\n"
+    elsif mermaid_style_result?(@current_block_lang)
       # For mermaid, add the image tag directly without a result block
       @output_lines << "\n" if blank_line_before_new_result.nil?
       @output_lines << result_output
@@ -51,25 +63,34 @@ module ResultHelper
   end
 
   def handle_existing_ruby_result_block(current_line, file_enum)
-    warn "Found existing '```ruby RESULT' block, passing through."
+    TestSilencer.warn_unless_testing("Found existing '```ruby RESULT' or '```ruby' result block, passing through.")
     @output_lines << current_line
     @state = :inside_result_block
   end
 
 
-  def execute_and_add_result(blank_line_before_new_result)
-      warn "Skipping empty code block for language '#{@current_block_lang}'." && return unless has_content?(@current_code_content)
+  def execute_and_add_result(blank_line_before_new_result, closing_line = nil)
+      TestSilencer.warn_unless_testing("Skipping empty code block for language '#{@current_block_lang}'.") && return unless has_content?(@current_code_content)
 
-    @output_lines << blank_line_before_new_result if blank_line_before_new_result
+    # For ruby blocks, don't add blank line since we're replacing the code block inline, not adding a RESULT block
+    @output_lines << blank_line_before_new_result if blank_line_before_new_result && !ruby_style_result?(@current_block_lang)
 
-    result_output = CodeExecutor.execute(@current_code_content, @current_block_lang, @temp_dir, @input_file_path, @current_block_explain)
+    result_output = CodeExecutor.execute(@current_code_content, @current_block_lang, @temp_dir, @input_file_path, @current_block_explain, @current_block_flamegraph)
 
     # Check if result contains a Dalibo link for psql explain queries
-    dalibo_link, clean_result = extract_dalibo_link(result_output)
+    dalibo_link, result_after_dalibo = extract_dalibo_link(result_output)
+
+    # Check if result contains a flamegraph link for psql flamegraph queries
+    flamegraph_link, clean_result = extract_flamegraph_link(result_after_dalibo)
 
     # Add the result block only if result=true (default)
     if @current_block_result
-      add_result_block(clean_result || result_output, blank_line_before_new_result)
+      add_result_block(clean_result || result_after_dalibo, blank_line_before_new_result, closing_line)
+    elsif ruby_style_result?(@current_block_lang)
+      # For ruby blocks with result=false, output the original code content without xmpfilter results
+      @output_lines << @current_code_content
+      @output_lines << (closing_line || "```\n")
+      @output_lines << "\n"
     end
 
     # Always add Dalibo link if it exists, even when result=false
@@ -81,30 +102,62 @@ module ResultHelper
         @output_lines << "\n#{dalibo_link}\n\n"
       end
     end
+
+    # Always add flamegraph link if it exists, even when result=false
+    if flamegraph_link
+      # Add appropriate spacing based on whether result block was shown
+      if @current_block_result || dalibo_link
+        @output_lines << "#{flamegraph_link}\n\n"
+      else
+        @output_lines << "\n#{flamegraph_link}\n\n"
+      end
+    end
   end
 
-  def skip_and_pass_through_result(lines_to_pass_through, file_enum, decision = nil)
+  def skip_and_pass_through_result(lines_to_pass_through, file_enum, decision = nil, closing_line = nil)
     # Handle run=false case where there are no lines to pass through
     if lines_to_pass_through.empty?
-      warn "Skipping execution due to run=false option."
+      TestSilencer.warn_unless_testing("Skipping execution due to run=false option.")
+      # For ruby blocks, we still need to output the code content and closing line
+      if ruby_style_result?(@current_block_lang)
+        @output_lines << @current_code_content
+        @output_lines << (closing_line || "```\n")
+        @output_lines << "\n"
+      end
       return
     end
 
     # Check if this is Dalibo content
     if decision && decision[:dalibo_content]
-      warn "Found existing Dalibo link for current #{@current_block_lang} block, skipping execution."
+      TestSilencer.warn_unless_testing("Found existing Dalibo link for current #{@current_block_lang} block, skipping execution.")
       @output_lines.concat(lines_to_pass_through)
       # No additional consumption needed for Dalibo links
       return
     end
 
+    # Check if this is flamegraph content
+    if decision && decision[:flamegraph_content]
+      TestSilencer.warn_unless_testing("Found existing flamegraph for current #{@current_block_lang} block, skipping execution.")
+      @output_lines.concat(lines_to_pass_through)
+      # No additional consumption needed for flamegraph links
+      return
+    end
+
     if mermaid_style_result?(@current_block_lang)
-      warn "Found existing mermaid SVG image for current #{@current_block_lang} block, skipping execution."
+      TestSilencer.warn_unless_testing("Found existing mermaid SVG image for current #{@current_block_lang} block, skipping execution.")
       @output_lines.concat(lines_to_pass_through)
       # For mermaid, no additional consumption needed since it's just an image line
+    elsif ruby_style_result?(@current_block_lang)
+      # For ruby blocks with existing old-style RESULT blocks, discard them and output inline results
+      TestSilencer.warn_unless_testing("Found existing ruby result for current #{@current_block_lang} block, skipping execution.")
+      @output_lines << @current_code_content
+      @output_lines << (closing_line || "```\n")
+      @output_lines << "\n"
+      # Always consume and discard the old-style RESULT block
+      consume_and_discard_result_block(file_enum)
     else
-      lang_specific_result_type = ruby_style_result?(@current_block_lang) ? "```ruby RESULT" : "```RESULT"
-      warn "Found existing '#{lang_specific_result_type}' block for current #{@current_block_lang} block, skipping execution."
+      lang_specific_result_type = "``` {result}"
+      TestSilencer.warn_unless_testing("Found existing '#{lang_specific_result_type}' block for current #{@current_block_lang} block, skipping execution.")
       @output_lines.concat(lines_to_pass_through)
       consume_result_block_content(file_enum)
     end
@@ -116,6 +169,12 @@ module ResultHelper
     end
   end
 
+  def consume_and_discard_result_block(file_enum)
+    consume_block_lines(file_enum) do |line|
+      # Discard the line - don't add to output
+    end
+  end
+
   def consume_existing_result_block(file_enum, consumed_lines)
     return if mermaid_style_result?(@current_block_lang)
 
@@ -124,6 +183,7 @@ module ResultHelper
     end
 
     consume_dalibo_link_if_present(file_enum, consumed_lines)
+    consume_flamegraph_link_if_present(file_enum, consumed_lines)
   end
 
 
@@ -135,7 +195,7 @@ module ResultHelper
         break if is_block_end?(result_block_line)
       end
     rescue StopIteration
-      warn "Warning: End of file reached while consuming result block."
+      TestSilencer.warn_unless_testing "Warning: End of file reached while consuming result block."
     end
   end
 end

data/lib/test_silencer.rb

@@ -0,0 +1,41 @@
+# Module to provide test-aware warning functionality
+module TestSilencer
+  # Helper method to detect if we're running in a test environment
+  def self.running_tests?
+    # Check for common test environment indicators
+    @running_tests ||= begin
+      caller.any? { |line| line.include?('/test/') || line.include?('minitest') || line.include?('rspec') } ||
+      defined?(Minitest) ||
+      ENV['RAILS_ENV'] == 'test' ||
+      ENV['RACK_ENV'] == 'test' ||
+      ($PROGRAM_NAME.include?('rake') && ARGV.include?('test')) ||
+      $PROGRAM_NAME.include?('rake_test_loader')
+    end
+  end
+
+  # Generic warn method that silences output during tests
+  def self.warn_unless_testing(message)
+    warn message unless running_tests?
+  end
+
+  # Silently abort during tests by raising SystemExit without printing the message
+  def self.abort_unless_testing(message)
+    if running_tests?
+      # During tests, raise SystemExit without printing the error message
+      raise SystemExit.new(1)
+    else
+      # In production, use normal abort which prints the message and exits
+      abort message
+    end
+  end
+
+  # Suppress Ruby warnings during tests
+  def self.setup_warning_suppression
+    if running_tests?
+      # Temporarily reduce verbosity during tests
+      original_verbose = $VERBOSE
+      $VERBOSE = nil
+      at_exit { $VERBOSE = original_verbose }
+    end
+  end
+end

data/markdown-run-sample/markdown-run-sample-flamegraph-20250604-233020-29c2a34ec32b.svg

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="1200" height="104" xmlns="http://www.w3.org/2000/svg">
+  <style>
+    .frame { stroke: white; stroke-width: 1; cursor: pointer; }
+    .frame:hover { stroke: black; stroke-width: 2; }
+    .frame-text { font-family: monospace; font-size: 20px; fill: white; pointer-events: none; }
+    .title { font-family: Arial; font-size: 16px; font-weight: bold; fill: #333; }
+    .subtitle { font-family: Arial; font-size: 12px; fill: #666; }
+  </style>
+
+  <!-- Title -->
+  <text x="600" y="20" class="title" text-anchor="middle">PostgreSQL Query Execution Plan Flamegraph</text>
+  <text x="600" y="35" class="subtitle" text-anchor="middle">Total Execution Time: 0.0ms</text>
+
+  <!-- Flamegraph -->
+  <g transform="translate(0, 45)">
+      <rect class="frame"
+            x="0.0"
+            y="0"
+            width="1200.0"
+            height="24"
+            fill="#95a5a6">
+        <title>Result [0.0ms]
+Time: 0.0ms
+Percentage: 100.0%</title>
+      </rect>
+<text class="frame-text" x="4.0" y="21">Result [0.0ms]</text>
+  </g>
+</svg>

data/markdown-run-sample.md

@@ -76,3 +76,12 @@ Page cache spills:                   0
 Schema Heap Usage:                   0 bytes
 Statement Heap/Lookaside Usage:      0 bytes
 ```
+
+```psql rerun flamegraph
+select 42 as answer;
+```
+
+```RESULT
+![PostgreSQL Query Flamegraph](pg-flamegraph-20250604-222931.svg)
+```
+

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: markdown-run
 version: !ruby/object:Gem::Version
-  version: 0.1.11
+  version: 0.2.0
 platform: ruby
 authors:
 - Aurélien Bottazini
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-04 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rcodetools
@@ -80,6 +79,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
 description: Run code blocks in Markdown files for Ruby, JavaScript, sqlite, psql,
   bash, zsh, and mermaid. Insert execution results next to the original code blocks.
   Generate SVG diagrams from mermaid blocks.
@@ -104,14 +117,20 @@ files:
 - lib/dalibo_helper.rb
 - lib/enum_helper.rb
 - lib/execution_decider.rb
+- lib/flamegraph_helper.rb
 - lib/frontmatter_parser.rb
 - lib/language_configs.rb
+- lib/language_resolver.rb
 - lib/markdown/run/version.rb
 - lib/markdown_file_writer.rb
 - lib/markdown_processor.rb
 - lib/markdown_run.rb
+- lib/pg_flamegraph_svg.rb
+- lib/postgres_helper.rb
 - lib/result_helper.rb
+- lib/test_silencer.rb
 - markdown-run-sample.md
+- markdown-run-sample/markdown-run-sample-flamegraph-20250604-233020-29c2a34ec32b.svg
 homepage: https://github.com/aurelienbottazini/markdown-run
 licenses:
 - MIT
@@ -119,7 +138,6 @@ metadata:
   homepage_uri: https://github.com/aurelienbottazini/markdown-run
   source_code_uri: https://github.com/aurelienbottazini/markdown-run
   changelog_uri: https://github.com/aurelienbottazini/markdown-run/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -134,8 +152,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Run code blocks in Markdown files
 test_files: []