markdown-run 0.1.11 → 0.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e078472cf91253d16b3341865954ead4ce1d6539d509c5ed6d54302c5a3147d
-  data.tar.gz: 76f40572409ed01a1797c4902896b783d3a0403783031fca8c8dff04a1499acf
+  metadata.gz: 2764390f72c90c38bd4862f78db857bd5585d13e59f1a2c87a3a9c67c2f66529
+  data.tar.gz: 95caace78ee0db7d12ac3a6a7a5a9abcddf32c1e946ff3d9cf71beed12c89a91
 SHA512:
-  metadata.gz: ea3ecacb94cbe3e52dacb9fdb4ea447790990cee631fd890f5389d483157d7e16621eda6dba68dddf13d1e1f5f499b8bc2ac3952e2ca1752f133f5aa496403b1
-  data.tar.gz: 8ae64565dc336f5158a877c54a02520bc6a0e6923c6bbdd705c2cff8c848ff832f0a0683f30c2e86df883a356d89e60269cebb219d9a9732212fc5edfd27fea6
+  metadata.gz: 90aea8dd4f03bc75969643bedd914ed2a8a8a1b45adf777d51fdfabb60deefd5e36cd1b73ac37225848b4663e12872a69c2ba4c3624029ac4c81c333a8eb6a8c
+  data.tar.gz: 7dfc12cda3abca94774e013904e2d9853713dce9c8b4059d6ca6bd90319ddff4f9f0d826c230d508f2438fdce57626f7868c1b94c9756ec3a122e0645be2121c

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+## [0.1.12] - 2025-06-04
+
+-   Added `flamegraph` option for psql code blocks to generate PostgreSQL query execution plan flamegraphs as SVG images
+-   PostgreSQL flamegraphs provide interactive, color-coded visualization of query performance with hover tooltips
+-   Flamegraph SVG files follow same directory structure as mermaid diagrams (organized by markdown file basename)
+-   Added flamegraph option support to frontmatter defaults and language-specific configurations
+
 ## [0.1.11] - 2025-06-04
 
 -   options are customizable with the yaml frontmatter

data/README.md

@@ -59,6 +59,7 @@ example vscode keybinding
 - `rerun=true` or `rerun=false` to control whether a code block should be re-executed if a result block already exists. `rerun=false` is the default if not specified
 - `result=true` or `result=false` to control whether the result block should be displayed after execution. `result=true` is the default if not specified. When `result=false`, the code still executes but the result block is hidden
 - `explain=true` or `explain=false` for psql code blocks to generate query execution plans with Dalibo visualization links. `explain=false` is the default if not specified
+- `flamegraph=true` or `flamegraph=false` for psql code blocks to generate PostgreSQL query execution plan flamegraphs as SVG images. `flamegraph=false` is the default if not specified
 
 Options can be combined. If `run=false` is specified, the code block will not execute regardless of the `rerun` setting. The `result` option only affects display of the result block, not code execution.
 
@@ -70,6 +71,7 @@ Options can also be specified using standalone syntax without explicit `=true`:
 - `rerun` is equivalent to `rerun=true`
 - `result` is equivalent to `result=true`
 - `explain` is equivalent to `explain=true`
+- `flamegraph` is equivalent to `flamegraph=true`
 
 Explicit assignments (e.g., `run=false`) take precedence over standalone options.
 
@@ -99,11 +101,57 @@ SELECT * FROM users WHERE id = 1;
 EXPLAIN (ANALYZE) SELECT * FROM large_table;
 ```
 
+```psql flamegraph
+SELECT u.name, COUNT(o.id) as order_count
+FROM users u
+LEFT JOIN orders o ON u.id = o.user_id
+WHERE u.created_at > '2024-01-01'
+GROUP BY u.id, u.name
+ORDER BY order_count DESC
+LIMIT 10;
+```
+
+```psql flamegraph=true result=false
+-- This will generate a flamegraph but hide the JSON result block
+SELECT * FROM complex_query_with_joins;
+```
+
 ```psql result=false explain
 SELECT * FROM large_table;
 -- This will execute the explain query and show the Dalibo link but hide the result block
 ```
 
+### PostgreSQL Flamegraphs
+
+PostgreSQL flamegraph blocks generate interactive SVG flamegraphs from query execution plans:
+
+```psql flamegraph
+SELECT users.*, orders.total
+FROM users
+JOIN orders ON users.id = orders.user_id
+WHERE users.created_at > '2024-01-01';
+```
+
+This generates:
+
+- An SVG flamegraph file in a directory named after the markdown file
+- Filename format: `my-document-flamegraph-20250118-143022-a1b2c3.svg`
+- Embedded image tag: `![PostgreSQL Query Flamegraph](my-document/my-document-flamegraph-20250118-143022-a1b2c3.svg)`
+
+**Flamegraph features:**
+
+- **Interactive**: Hover over rectangles to see detailed timing information
+- **Color-coded**: Different colors for operation types (red=seq scans, green=index scans, blue=joins, etc.)
+- **Hierarchical**: Shows query plan structure visually
+- **Performance insights**: Width represents execution time, making bottlenecks immediately visible
+
+**What flamegraphs help identify:**
+
+- Slow operations (widest rectangles)
+- Query plan structure (nested relationships)
+- Inefficient operations (color-coded by type)
+- Execution time distribution across plan nodes
+
 ### Mermaid diagrams
 
 Mermaid blocks generate SVG files and insert markdown image tags:
@@ -163,6 +211,7 @@ markdown-run:
 - `rerun`: Control whether to re-execute if result exists (default: `false`)
 - `result`: Control whether to show result blocks (default: `true`)
 - `explain`: For psql blocks, generate explain plans (default: `false`)
+- `flamegraph`: For psql blocks, generate flamegraph SVGs (default: `false`)
 
 **Examples:**
 
@@ -184,6 +233,14 @@ markdown-run:
     explain: true
 ```
 
+Enable flamegraphs by default for all psql blocks:
+
+```yaml
+markdown-run:
+  psql:
+    flamegraph: true
+```
+
 Language-specific settings override global defaults:
 
 ```yaml

data/Rakefile

@@ -19,4 +19,14 @@ task :flog_detailed do
   system("flog -d lib/ exe/ test/")
 end
 
+desc "Release"
+task :release do
+  `gem bump`
+  `bundle`
+  `git commit --amend`
+  `git push`
+  `git push --tags`
+  `gem release`
+end
+
 task default: :test

data/lib/code_block_helper.rb

@@ -10,6 +10,7 @@ module CodeBlockHelper
     @current_block_rerun = false
     @current_block_run = true
     @current_block_explain = false
+    @current_block_flamegraph = false
     @current_block_result = true
   end
 
@@ -20,6 +21,7 @@ module CodeBlockHelper
     @current_block_rerun = @code_block_parser.parse_rerun_option(options_string, @current_block_lang)
     @current_block_run = @code_block_parser.parse_run_option(options_string, @current_block_lang)
     @current_block_explain = @code_block_parser.parse_explain_option(options_string, @current_block_lang)
+    @current_block_flamegraph = @code_block_parser.parse_flamegraph_option(options_string, @current_block_lang)
     @current_block_result = @code_block_parser.parse_result_option(options_string, @current_block_lang)
     @state = :inside_code_block
     @current_code_content = ""
@@ -46,7 +48,7 @@ module CodeBlockHelper
   end
 
   def decide_execution(file_enum)
-    decider = ExecutionDecider.new(@current_block_run, @current_block_rerun, @current_block_lang, @current_block_explain, @current_block_result)
+    decider = ExecutionDecider.new(@current_block_run, @current_block_rerun, @current_block_lang, @current_block_explain, @current_block_flamegraph, @current_block_result)
     decision = decider.decide(file_enum, method(:result_block_regex))
 
     # Handle the consume_existing flag for rerun scenarios

data/lib/code_block_parser.rb

@@ -49,6 +49,11 @@ class CodeBlockParser
     parse_boolean_option(options_string, "explain", default_value)
   end
 
+  def parse_flamegraph_option(options_string, language = nil)
+    default_value = @frontmatter_parser.get_default_value("flamegraph", language, false)
+    parse_boolean_option(options_string, "flamegraph", default_value)
+  end
+
   def parse_result_option(options_string, language = nil)
     default_value = @frontmatter_parser.get_default_value("result", language, true)
     parse_boolean_option(options_string, "result", default_value)

data/lib/code_executor.rb

@@ -3,11 +3,11 @@ require "open3"
 require_relative "language_configs"
 
 class CodeExecutor
-  def self.execute(code_content, lang, temp_dir, input_file_path = nil, explain = false)
-    new.execute(code_content, lang, temp_dir, input_file_path, explain)
+  def self.execute(code_content, lang, temp_dir, input_file_path = nil, explain = false, flamegraph = false)
+    new.execute(code_content, lang, temp_dir, input_file_path, explain, flamegraph)
   end
 
-  def execute(code_content, lang, temp_dir, input_file_path = nil, explain = false)
+  def execute(code_content, lang, temp_dir, input_file_path = nil, explain = false, flamegraph = false)
     lang_key = lang.downcase
     lang_config = SUPPORTED_LANGUAGES[lang_key]
 
@@ -15,14 +15,12 @@ class CodeExecutor
 
     warn "Executing #{lang_key} code block..."
 
-    result = execute_with_config(code_content, lang_config, temp_dir, lang_key, input_file_path, explain)
-    process_execution_result(result, lang_config, lang_key, explain)
+    result = execute_with_config(code_content, lang_config, temp_dir, lang_key, input_file_path, explain, flamegraph)
+    process_execution_result(result, lang_config, lang_key, explain, flamegraph)
   end
 
   private
 
-
-
   def stderr_has_content?(stderr_output)
     stderr_output && !stderr_output.strip.empty?
   end
@@ -32,23 +30,23 @@ class CodeExecutor
     "ERROR: Unsupported language: #{lang}"
   end
 
-  def execute_with_config(code_content, lang_config, temp_dir, lang_key, input_file_path = nil, explain = false)
+  def execute_with_config(code_content, lang_config, temp_dir, lang_key, input_file_path = nil, explain = false, flamegraph = false)
     cmd_lambda = lang_config[:command]
     temp_file_suffix = lang_config[:temp_file_suffix]
 
     if temp_file_suffix
-      execute_with_temp_file(code_content, cmd_lambda, temp_file_suffix, temp_dir, lang_key, input_file_path, explain)
+      execute_with_temp_file(code_content, cmd_lambda, temp_file_suffix, temp_dir, lang_key, input_file_path, explain, flamegraph)
     else
-      execute_direct_command(code_content, cmd_lambda, explain)
+      execute_direct_command(code_content, cmd_lambda, input_file_path, explain, flamegraph)
     end
   end
 
-  def execute_with_temp_file(code_content, cmd_lambda, temp_file_suffix, temp_dir, lang_key, input_file_path = nil, explain = false)
+  def execute_with_temp_file(code_content, cmd_lambda, temp_file_suffix, temp_dir, lang_key, input_file_path = nil, explain = false, flamegraph = false)
     result = nil
     Tempfile.create([lang_key, temp_file_suffix], temp_dir) do |temp_file|
       temp_file.write(code_content)
       temp_file.close
-      command_to_run, exec_options = cmd_lambda.call(code_content, temp_file.path, input_file_path, explain)
+      command_to_run, exec_options = cmd_lambda.call(code_content, temp_file.path, input_file_path, explain, flamegraph)
 
       # Extract output_path if present (for mermaid)
       output_path = exec_options.delete(:output_path) if exec_options.is_a?(Hash)
@@ -58,27 +56,35 @@ class CodeExecutor
         stdout: captured_stdout,
         stderr: captured_stderr,
         status: captured_status_obj,
-        output_path: output_path # For mermaid SVG output
+        output_path: output_path, # For mermaid SVG output
+        input_file_path: input_file_path # Pass through for flamegraph generation
       }
     end
     result
   end
 
-  def execute_direct_command(code_content, cmd_lambda, explain = false)
-    command_to_run, exec_options = cmd_lambda.call(code_content, nil, nil, explain)
+  def execute_direct_command(code_content, cmd_lambda, input_file_path = nil, explain = false, flamegraph = false)
+    command_to_run, exec_options = cmd_lambda.call(code_content, nil, input_file_path, explain, flamegraph)
     captured_stdout, captured_stderr, captured_status_obj = Open3.capture3(command_to_run, **exec_options)
-    { stdout: captured_stdout, stderr: captured_stderr, status: captured_status_obj }
+    { stdout: captured_stdout, stderr: captured_stderr, status: captured_status_obj, input_file_path: input_file_path }
   end
 
-  def process_execution_result(result, lang_config, lang_key, explain = false)
+  def process_execution_result(result, lang_config, lang_key, explain = false, flamegraph = false)
     exit_status, result_output, stderr_output = format_captured_output(result, lang_config)
 
     if exit_status != 0
       result_output = add_error_to_output(exit_status, lang_config, lang_key, result_output, stderr_output)
     elsif lang_config && lang_config[:result_handling] == :mermaid_svg
       result_output = handle_mermaid_svg_result(result, lang_key)
-    elsif explain && lang_key == "psql"
-      result_output = handle_psql_explain_result(result_output)
+    else
+      # Handle psql explain and flamegraph processing (both can be enabled)
+      if explain && lang_key == "psql"
+        result_output = handle_psql_explain_result(result_output)
+      end
+
+      if flamegraph && lang_key == "psql"
+        result_output = handle_psql_flamegraph_result(result_output, result[:input_file_path])
+      end
     end
 
     result_output
@@ -169,6 +175,78 @@ class CodeExecutor
     end
   end
 
+  def handle_psql_flamegraph_result(result_output, input_file_path = nil)
+    require_relative 'pg_flamegraph_svg'
+
+    begin
+      # Extract clean JSON from result_output (might contain Dalibo link prefix)
+      json_text = if result_output.start_with?("DALIBO_LINK:")
+        # Extract the JSON part after the Dalibo link line
+        lines = result_output.split("\n", 2)
+        lines[1] || ""
+      else
+        result_output.strip
+      end
+
+      # Parse the EXPLAIN JSON output
+      json_data = JSON.parse(json_text)
+
+      # Generate SVG flamegraph
+      flamegraph_generator = PostgreSQLFlameGraphSVG.new(JSON.generate(json_data))
+      svg_content = flamegraph_generator.generate_svg
+
+      # Save SVG file following same pattern as mermaid
+      if input_file_path
+        # Extract markdown file basename without extension
+        md_basename = File.basename(input_file_path, ".*")
+
+        # Create directory named after the markdown file
+        output_dir = File.join(File.dirname(input_file_path), md_basename)
+        Dir.mkdir(output_dir) unless Dir.exist?(output_dir)
+
+        # Generate unique filename with markdown basename prefix
+        timestamp = Time.now.strftime("%Y%m%d-%H%M%S")
+        random_suffix = SecureRandom.hex(6)
+        svg_filename = "#{md_basename}-flamegraph-#{timestamp}-#{random_suffix}.svg"
+        output_path = File.join(output_dir, svg_filename)
+      else
+        # Fallback to simple naming
+        timestamp = Time.now.strftime("%Y%m%d-%H%M%S")
+        output_path = "pg-flamegraph-#{timestamp}.svg"
+      end
+
+      # Write SVG file
+      File.write(output_path, svg_content)
+
+      # Generate relative path for markdown
+      if input_file_path
+        relative_path = "#{File.basename(output_dir)}/#{File.basename(output_path)}"
+      else
+        relative_path = File.basename(output_path)
+      end
+
+      warn "Generated PostgreSQL flamegraph: #{relative_path}"
+
+      # Return a special format that the markdown processor can parse
+      # Preserve any existing Dalibo link prefix
+      if result_output.start_with?("DALIBO_LINK:")
+        lines = result_output.split("\n", 2)
+        dalibo_part = lines[0]
+        json_part = lines[1] || ""
+        "#{dalibo_part}\nFLAMEGRAPH_LINK:#{relative_path}\n#{json_part}"
+      else
+        "FLAMEGRAPH_LINK:#{relative_path}\n#{json_text}"
+      end
+
+    rescue JSON::ParserError => e
+      warn "Error parsing EXPLAIN JSON: #{e.message}"
+      result_output
+    rescue => e
+      warn "Error generating flamegraph: #{e.message}"
+      result_output
+    end
+  end
+
   private
 
   def submit_plan_to_dalibo(plan_json)

data/lib/dalibo_helper.rb

@@ -9,7 +9,7 @@ module DaliboHelper
       lines = result_output.split("\n", 2)
       dalibo_url = lines[0].sub(DALIBO_LINK_PREFIX, "")
       clean_result = lines[1] || ""
-      dalibo_link = "**Dalibo Visualization:** [View Query Plan](#{dalibo_url})"
+      dalibo_link = "[Dalibo](#{dalibo_url})"
       [dalibo_link, clean_result]
     else
       [nil, result_output]
@@ -25,7 +25,7 @@ module DaliboHelper
 
         if is_blank_line?(next_line)
           consumed_lines << file_enum.next
-        elsif next_line&.start_with?("**Dalibo Visualization:**")
+        elsif next_line&.start_with?("[Dalibo]")
           consumed_lines << file_enum.next
         else
           # Hit something that's not a blank line or Dalibo link, stop consuming

data/lib/execution_decider.rb

@@ -3,11 +3,12 @@ require_relative "enum_helper"
 class ExecutionDecider
   include EnumHelper
 
-  def initialize(current_block_run, current_block_rerun, current_block_lang, current_block_explain = false, current_block_result = true)
+  def initialize(current_block_run, current_block_rerun, current_block_lang, current_block_explain = false, current_block_flamegraph = false, current_block_result = true)
     @current_block_run = current_block_run
     @current_block_rerun = current_block_rerun
     @current_block_lang = current_block_lang
     @current_block_explain = current_block_explain
+    @current_block_flamegraph = current_block_flamegraph
     @current_block_result = current_block_result
   end
 
@@ -21,8 +22,10 @@ class ExecutionDecider
       handle_immediate_result_block(file_enum)
     elsif is_blank_line?(peek1)
       handle_blank_line_scenario(file_enum, expected_header_regex)
-    elsif @current_block_explain && is_dalibo_link?(peek1)
+    elsif (@current_block_explain || @current_block_flamegraph) && is_dalibo_link?(peek1)
       handle_immediate_dalibo_link(file_enum)
+    elsif @current_block_flamegraph && is_flamegraph_link?(peek1)
+      handle_immediate_flamegraph_link(file_enum)
     else
       execute_without_existing_result
     end
@@ -48,11 +51,11 @@ class ExecutionDecider
 
   def handle_blank_line_scenario(file_enum, expected_header_regex)
     consumed_blank_line = file_enum.next
-    
+
     # Look ahead past multiple blank lines to find actual content
     peek2 = peek_next_line(file_enum)
     additional_blanks = []
-    
+
     # Consume consecutive blank lines
     while is_blank_line?(peek2)
       additional_blanks << file_enum.next
@@ -61,8 +64,10 @@ class ExecutionDecider
 
     if line_matches_pattern?(peek2, expected_header_regex)
       handle_result_after_blank_lines(file_enum, consumed_blank_line, additional_blanks)
-    elsif @current_block_explain && is_dalibo_link?(peek2)
+    elsif (@current_block_explain || @current_block_flamegraph) && is_dalibo_link?(peek2)
       handle_dalibo_after_blank_lines(file_enum, consumed_blank_line, additional_blanks)
+    elsif @current_block_flamegraph && is_flamegraph_link?(peek2)
+      handle_flamegraph_after_blank_lines(file_enum, consumed_blank_line, additional_blanks)
     else
       execute_with_blank_lines(consumed_blank_line, additional_blanks)
     end
@@ -194,7 +199,7 @@ class ExecutionDecider
     # Consume all consecutive Dalibo links and blank lines
     loop do
       next_line = peek_next_line(file_enum)
-      
+
       if is_blank_line?(next_line) || is_dalibo_link?(next_line)
         consumed_line = file_enum.next
         consumed_lines << consumed_line
@@ -205,7 +210,7 @@ class ExecutionDecider
   end
 
   def is_dalibo_link?(line)
-    line&.start_with?("**Dalibo Visualization:**")
+    line&.start_with?("[Dalibo]")
   end
 
   def line_matches_pattern?(line, pattern)
@@ -217,9 +222,78 @@ class ExecutionDecider
   end
 
   def should_auto_replace_dalibo_link?
-    # Auto-replace Dalibo links when using explain with result=false
+    # Auto-replace Dalibo links when using explain or flamegraph with result=false
     # This makes sense because with result=false, there's only a Dalibo link,
     # so it should be updated on each run
-    @current_block_explain && !@current_block_result
+    (@current_block_explain || @current_block_flamegraph) && !@current_block_result
+  end
+
+  def is_flamegraph_link?(line)
+    line&.start_with?("![PostgreSQL Query Flamegraph]")
+  end
+
+  def handle_flamegraph_after_blank_lines(file_enum, consumed_blank_line, additional_blanks)
+    # For flamegraph result=false, always replace existing flamegraph links
+    # For flamegraph result=true, follow normal rerun logic
+    if should_auto_replace_flamegraph_link? || @current_block_rerun
+      execute_with_consumed_flamegraph_and_blanks(file_enum, consumed_blank_line, additional_blanks)
+    else
+      skip_with_blanks_and_flamegraph(file_enum, consumed_blank_line, additional_blanks)
+    end
+  end
+
+  def handle_immediate_flamegraph_link(file_enum)
+    # For flamegraph result=false, always replace existing flamegraph links
+    # For flamegraph result=true, follow normal rerun logic
+    if should_auto_replace_flamegraph_link? || @current_block_rerun
+      execute_with_consumed_flamegraph(file_enum)
+    else
+      skip_with_existing_flamegraph(file_enum)
+    end
+  end
+
+  def execute_with_consumed_flamegraph(file_enum)
+    consumed_lines = []
+    consume_flamegraph_links(file_enum, consumed_lines)
+    { execute: true, consumed_lines: consumed_lines, consume_existing_flamegraph: true }
+  end
+
+  def skip_with_existing_flamegraph(file_enum)
+    consumed_lines = []
+    consume_flamegraph_links(file_enum, consumed_lines)
+    { execute: false, lines_to_pass_through: consumed_lines, flamegraph_content: true }
+  end
+
+  def execute_with_consumed_flamegraph_and_blanks(file_enum, consumed_blank_line, additional_blanks)
+    consumed_lines = [consumed_blank_line] + additional_blanks
+    consume_flamegraph_links(file_enum, consumed_lines)
+    { execute: true, consumed_lines: consumed_lines, blank_line: consumed_blank_line, consume_existing_flamegraph: true }
+  end
+
+  def skip_with_blanks_and_flamegraph(file_enum, consumed_blank_line, additional_blanks)
+    consumed_lines = [consumed_blank_line] + additional_blanks
+    consume_flamegraph_links(file_enum, consumed_lines)
+    { execute: false, lines_to_pass_through: consumed_lines, flamegraph_content: true }
+  end
+
+  def consume_flamegraph_links(file_enum, consumed_lines)
+    # Consume all consecutive flamegraph links and blank lines
+    loop do
+      next_line = peek_next_line(file_enum)
+
+      if is_blank_line?(next_line) || is_flamegraph_link?(next_line)
+        consumed_line = file_enum.next
+        consumed_lines << consumed_line
+      else
+        break
+      end
+    end
+  end
+
+  def should_auto_replace_flamegraph_link?
+    # Auto-replace flamegraph links when using flamegraph with result=false
+    # This makes sense because with result=false, there's only a flamegraph link,
+    # so it should be updated on each run
+    @current_block_flamegraph && !@current_block_result
   end
 end

data/lib/flamegraph_helper.rb

@@ -0,0 +1,39 @@
+module FlamegraphHelper
+  private
+
+  FLAMEGRAPH_LINK_PREFIX = "FLAMEGRAPH_LINK:"
+
+  def extract_flamegraph_link(result_output)
+    # Check if the result contains a flamegraph link marker
+    if result_output.start_with?(FLAMEGRAPH_LINK_PREFIX)
+      lines = result_output.split("\n", 2)
+      flamegraph_path = lines[0].sub(FLAMEGRAPH_LINK_PREFIX, "")
+      clean_result = lines[1] || ""
+      flamegraph_link = "![PostgreSQL Query Flamegraph](#{flamegraph_path})"
+      [flamegraph_link, clean_result]
+    else
+      [nil, result_output]
+    end
+  end
+
+  def consume_flamegraph_link_if_present(file_enum, consumed_lines)
+    # Look ahead to see if there are flamegraph links after the result block
+    begin
+      # Keep consuming blank lines and flamegraph links until we hit something else
+      loop do
+        next_line = peek_next_line(file_enum)
+
+        if is_blank_line?(next_line)
+          consumed_lines << file_enum.next
+        elsif next_line&.start_with?("![PostgreSQL Query Flamegraph]")
+          consumed_lines << file_enum.next
+        else
+          # Hit something that's not a blank line or flamegraph link, stop consuming
+          break
+        end
+      end
+    rescue StopIteration
+      # End of file reached, nothing more to consume
+    end
+  end
+end

data/lib/language_configs.rb

@@ -1,7 +1,7 @@
 require 'securerandom'
 
 JS_CONFIG = {
-  command: ->(_code_content, temp_file_path, input_file_path = nil, explain = false) {
+  command: ->(_code_content, temp_file_path, input_file_path = nil, explain = false, flamegraph = false) {
     # Check if bun is available
     bun_exists = system("command -v bun > /dev/null 2>&1")
     if bun_exists
@@ -16,20 +16,20 @@ JS_CONFIG = {
 }.freeze
 
 SQLITE_CONFIG = {
-  command: ->(code_content, temp_file_path, input_file_path = nil, explain = false) { [ "sqlite3 #{temp_file_path}", { stdin_data: code_content } ] },
+  command: ->(code_content, temp_file_path, input_file_path = nil, explain = false, flamegraph = false) { [ "sqlite3 #{temp_file_path}", { stdin_data: code_content } ] },
   temp_file_suffix: ".db" # Temp file is the database
 }.freeze
 
 SUPPORTED_LANGUAGES = {
   "psql" => {
-    command: ->(code_content, _temp_file_path, input_file_path = nil, explain = false) {
+    command: ->(code_content, _temp_file_path, input_file_path = nil, explain = false, flamegraph = false) {
       psql_exists = system("command -v psql > /dev/null 2>&1")
       unless psql_exists
         abort "Error: psql command not found. Please install PostgreSQL or ensure psql is in your PATH."
       end
 
-      # Modify the SQL query if explain option is enabled
-      if explain
+      # Modify the SQL query if explain or flamegraph option is enabled
+      if explain || flamegraph
         # Wrap the query with EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)
         # Remove any trailing semicolons and whitespace, then add our EXPLAIN wrapper
         clean_query = code_content.strip.gsub(/;\s*$/, '')
@@ -41,7 +41,7 @@ SUPPORTED_LANGUAGES = {
     }
   },
   "ruby" => {
-    command: ->(_code_content, temp_file_path, input_file_path = nil, explain = false) {
+    command: ->(_code_content, temp_file_path, input_file_path = nil, explain = false, flamegraph = false) {
       xmpfilter_exists = system("command -v xmpfilter > /dev/null 2>&1")
       unless xmpfilter_exists
         abort "Error: xmpfilter command not found. Please install xmpfilter or ensure it is in your PATH."
@@ -57,7 +57,7 @@ SUPPORTED_LANGUAGES = {
   "sqlite" => SQLITE_CONFIG,
   "sqlite3" => SQLITE_CONFIG, # Alias for sqlite
   "bash" => {
-    command: ->(_code_content, temp_file_path, input_file_path = nil, explain = false) {
+    command: ->(_code_content, temp_file_path, input_file_path = nil, explain = false, flamegraph = false) {
       bash_exists = system("command -v bash > /dev/null 2>&1")
       unless bash_exists
         abort "Error: bash command not found. Please ensure bash is in your PATH."
@@ -67,7 +67,7 @@ SUPPORTED_LANGUAGES = {
     temp_file_suffix: ".sh"
   },
   "zsh" => {
-    command: ->(_code_content, temp_file_path, input_file_path = nil, explain = false) {
+    command: ->(_code_content, temp_file_path, input_file_path = nil, explain = false, flamegraph = false) {
       zsh_exists = system("command -v zsh > /dev/null 2>&1")
       unless zsh_exists
         abort "Error: zsh command not found. Please ensure zsh is in your PATH."
@@ -77,7 +77,7 @@ SUPPORTED_LANGUAGES = {
     temp_file_suffix: ".zsh"
   },
   "sh" => {
-    command: ->(_code_content, temp_file_path, input_file_path = nil, explain = false) {
+    command: ->(_code_content, temp_file_path, input_file_path = nil, explain = false, flamegraph = false) {
       sh_exists = system("command -v sh > /dev/null 2>&1")
       unless sh_exists
         abort "Error: sh command not found. Please ensure sh is in your PATH."
@@ -87,7 +87,7 @@ SUPPORTED_LANGUAGES = {
     temp_file_suffix: ".sh"
   },
   "mermaid" => {
-    command: ->(code_content, temp_file_path, input_file_path = nil, explain = false) {
+    command: ->(code_content, temp_file_path, input_file_path = nil, explain = false, flamegraph = false) {
       mmdc_exists = system("command -v mmdc > /dev/null 2>&1")
       unless mmdc_exists
         abort "Error: mmdc command not found. Please install @mermaid-js/mermaid-cli: npm install -g @mermaid-js/mermaid-cli"

data/lib/markdown/run/version.rb

@@ -2,6 +2,6 @@
 
 module Markdown
   module Run
-    VERSION = "0.1.11"
+    VERSION = "0.1.12"
   end
 end

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/result_helper.rb

@@ -1,4 +1,8 @@
+require_relative "flamegraph_helper"
+
 module ResultHelper
+  include FlamegraphHelper
+
   private
 
   def ruby_style_result?(lang)
@@ -62,14 +66,17 @@ module ResultHelper
 
     @output_lines << blank_line_before_new_result if blank_line_before_new_result
 
-    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)
     end
 
     # Always add Dalibo link if it exists, even when result=false
@@ -81,6 +88,16 @@ 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)
@@ -98,6 +115,14 @@ module ResultHelper
       return
     end
 
+    # Check if this is flamegraph content
+    if decision && decision[:flamegraph_content]
+      warn "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."
       @output_lines.concat(lines_to_pass_through)
@@ -124,6 +149,7 @@ module ResultHelper
     end
 
     consume_dalibo_link_if_present(file_enum, consumed_lines)
+    consume_flamegraph_link_if_present(file_enum, consumed_lines)
   end
 
 

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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: markdown-run
 version: !ruby/object:Gem::Version
-  version: 0.1.11
+  version: 0.1.12
 platform: ruby
 authors:
 - Aurélien Bottazini
@@ -104,12 +104,14 @@ 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/markdown/run/version.rb
 - lib/markdown_file_writer.rb
 - lib/markdown_processor.rb
 - lib/markdown_run.rb
+- lib/pg_flamegraph_svg.rb
 - lib/result_helper.rb
 - markdown-run-sample.md
 homepage: https://github.com/aurelienbottazini/markdown-run