markdown-run 0.1.10 → 0.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1139e0ccb6ed1b5b4ee2cef44cf067c83fc8a92ad750eae2e256725282534b68
-  data.tar.gz: 8887f778eaec56e6bdbb84d0a48f8db82fbd52cabbcdea01c48f4cffb5ff410b
+  metadata.gz: 2764390f72c90c38bd4862f78db857bd5585d13e59f1a2c87a3a9c67c2f66529
+  data.tar.gz: 95caace78ee0db7d12ac3a6a7a5a9abcddf32c1e946ff3d9cf71beed12c89a91
 SHA512:
-  metadata.gz: 6656d86bf179be5a044a95ccbc1a9c11e68642a35ed2ffa99138dc0de653ed4b2e176a9763f08b765d409ec232e4b9eda4779b166c97b7304ed156a48b147c93
-  data.tar.gz: 3f8771ece0365e9a1c7073a6d749d41570776b59e9cbe0c38383516cce9cf0261a2ba287aadb30278ee0cf72e859fe4b4cb072fa89294bc3a525700fdec5ff9c
+  metadata.gz: 90aea8dd4f03bc75969643bedd914ed2a8a8a1b45adf777d51fdfabb60deefd5e36cd1b73ac37225848b4663e12872a69c2ba4c3624029ac4c81c333a8eb6a8c
+  data.tar.gz: 7dfc12cda3abca94774e013904e2d9853713dce9c8b4059d6ca6bd90319ddff4f9f0d826c230d508f2438fdce57626f7868c1b94c9756ec3a122e0645be2121c

data/CHANGELOG.md

@@ -1,49 +1,60 @@
 ## [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
+
 ## [0.1.10] - 2025-06-03
 
-- standalone options for codeblocks (run instead of run=true)
-- explain option for psql code blocks with Dalibo visualization links
-- Fixed Dalibo URL generation to properly submit plans via HTTP POST
-- Added result option to control result block visibility (result=false hides result blocks while still executing code)
+-   standalone options for codeblocks (run instead of run=true)
+-   explain option for psql code blocks with Dalibo visualization links
+-   Fixed Dalibo URL generation to properly submit plans via HTTP POST
+-   Added result option to control result block visibility (result=false hides result blocks while still executing code)
 
 ## [0.1.9] - 2025-06-02
 
-- mermaid codeblocks
+-   mermaid codeblocks
 
 ## [0.1.8] - 2025-06-01
 
-- Added run option
+-   Added run option
 
 ## [0.1.7] - 2025-06-01
 
-- Added rerun functionality
+-   Added rerun functionality
 
 ## [0.1.6] - 2025-06-01
 
-- Refactor code to state pattern
-- Add yaml frontmatter to support aliases for code blocks
+-   Refactor code to state pattern
+-   Add yaml frontmatter to support aliases for code blocks
 
 ## [0.1.5] - 2025-05-19
 
-- Remove gif files from release
+-   Remove gif files from release
 
 ## [0.1.4] - 2025-05-18
 
-- Add support for zsh, bash, sh
+-   Add support for zsh, bash, sh
 
 ## [0.1.3] - 2025-05-14
 
-- Fix missing minitest dep
+-   Fix missing minitest dep
 
 ## [0.1.2] - 2025-05-14
 
-- Gemfile update
+-   Gemfile update
 
 ## [0.1.1] - 2025-05-14
 
-- Added checks for missing dependencies
+-   Added checks for missing dependencies
 
 ## [0.1.0] - 2025-05-13
 
-- Initial release
+-   Initial release

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:
@@ -135,6 +183,74 @@ markdown-run:
     - sql: psql
 ```
 
+### Setting Defaults
+
+You can override the default behavior for code block options using frontmatter:
+
+```yaml
+markdown-run:
+  defaults:
+    rerun: true
+    result: false
+  psql:
+    explain: true
+  ruby:
+    rerun: false
+```
+
+**Priority order (highest to lowest):**
+
+1. Explicit options in code blocks (e.g., `rerun=true`)
+2. Language-specific defaults (e.g., `psql: { explain: true }`)
+3. Global defaults (e.g., `defaults: { rerun: true }`)
+4. Built-in application defaults
+
+**Available options for defaults:**
+
+- `run`: Control whether code blocks execute (default: `true`)
+- `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:**
+
+Make all code blocks rerun by default:
+
+```yaml
+markdown-run:
+  defaults:
+    rerun: true
+```
+
+Hide result blocks by default but enable explain for psql:
+
+```yaml
+markdown-run:
+  defaults:
+    result: false
+  psql:
+    explain: true
+```
+
+Enable flamegraphs by default for all psql blocks:
+
+```yaml
+markdown-run:
+  psql:
+    flamegraph: true
+```
+
+Language-specific settings override global defaults:
+
+```yaml
+markdown-run:
+  defaults:
+    rerun: false # Global default
+  ruby:
+    rerun: true # Ruby blocks will rerun, others won't
+```
+
 ## Demo
 
 ![VSCode Usage](docs/markdown-run-vscode.gif)

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

@@ -0,0 +1,64 @@
+module CodeBlockHelper
+  private
+
+  def reset_code_block_state
+    @state = :outside_code_block
+    @current_code_content = ""
+    @current_block_lang = ""
+
+
+    @current_block_rerun = false
+    @current_block_run = true
+    @current_block_explain = false
+    @current_block_flamegraph = false
+    @current_block_result = true
+  end
+
+
+  def start_code_block(current_line, lang, options_string = nil)
+    @output_lines << current_line
+    @current_block_lang = resolve_language(lang)
+    @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 = ""
+  end
+
+  def accumulate_code_content(current_line)
+    @current_code_content += current_line
+    @output_lines << current_line
+  end
+
+  def end_code_block(current_line, file_enum)
+    @output_lines << current_line
+
+    decision = decide_execution(file_enum)
+
+    if decision[:execute]
+      # If we consumed lines for rerun, don't add them to output (they'll be replaced)
+      execute_and_add_result(decision[:blank_line])
+    else
+      skip_and_pass_through_result(decision[:lines_to_pass_through], file_enum, decision)
+    end
+
+    reset_code_block_state
+  end
+
+  def decide_execution(file_enum)
+    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
+    if decision[:consume_existing]
+      consume_existing_result_block(file_enum, decision[:consumed_lines])
+    elsif decision[:consume_existing_dalibo]
+      # Dalibo links are already consumed in the decision process
+      # Just acknowledge they were consumed
+    end
+
+    decision
+  end
+end

data/lib/code_block_parser.rb

@@ -34,20 +34,29 @@ class CodeBlockParser
     line.strip == BLOCK_END_PATTERN
   end
 
-  def parse_run_option(options_string)
-    parse_boolean_option(options_string, "run", true)
+  def parse_run_option(options_string, language = nil)
+    default_value = @frontmatter_parser.get_default_value("run", language, true)
+    parse_boolean_option(options_string, "run", default_value)
   end
 
-  def parse_rerun_option(options_string)
-    parse_boolean_option(options_string, "rerun", false)
+  def parse_rerun_option(options_string, language = nil)
+    default_value = @frontmatter_parser.get_default_value("rerun", language, false)
+    parse_boolean_option(options_string, "rerun", default_value)
   end
 
-  def parse_explain_option(options_string)
-    parse_boolean_option(options_string, "explain", false)
+  def parse_explain_option(options_string, language = nil)
+    default_value = @frontmatter_parser.get_default_value("explain", language, false)
+    parse_boolean_option(options_string, "explain", default_value)
   end
 
-  def parse_result_option(options_string)
-    parse_boolean_option(options_string, "result", true)
+  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)
   end
 
   private

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,34 +15,38 @@ 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
+
   def handle_unsupported_language(lang)
     warn "Unsupported language: #{lang}"
     "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)
@@ -52,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
@@ -163,35 +175,101 @@ 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)
     begin
-      # Start with HTTPS directly to avoid the HTTP->HTTPS redirect
       uri = URI('https://explain.dalibo.com/new')
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = true
-      http.read_timeout = 10  # 10 seconds timeout
+      http.read_timeout = 10
 
-      # Prepare the JSON payload
       payload = {
         'plan' => plan_json,
         'title' => "Query Plan - #{Time.now.strftime('%Y-%m-%d %H:%M:%S')}",
         'query' => ''
       }
 
-      # Create the POST request
       request = Net::HTTP::Post.new(uri)
       request['Content-Type'] = 'application/json'
       request.body = JSON.generate(payload)
 
-      # Send the request and follow redirects to get the final URL
       response = http.request(request)
 
-      # Dalibo returns a redirect to the plan URL
       if response.is_a?(Net::HTTPRedirection)
         location = response['location']
-        # Make sure it's a full URL
         if location
           if location.start_with?('/')
             location = "https://explain.dalibo.com#{location}"

data/lib/dalibo_helper.rb

@@ -0,0 +1,39 @@
+module DaliboHelper
+  private
+
+  DALIBO_LINK_PREFIX = "DALIBO_LINK:"
+
+  def extract_dalibo_link(result_output)
+    # Check if the result contains a Dalibo link marker
+    if result_output.start_with?(DALIBO_LINK_PREFIX)
+      lines = result_output.split("\n", 2)
+      dalibo_url = lines[0].sub(DALIBO_LINK_PREFIX, "")
+      clean_result = lines[1] || ""
+      dalibo_link = "[Dalibo](#{dalibo_url})"
+      [dalibo_link, clean_result]
+    else
+      [nil, result_output]
+    end
+  end
+
+  def consume_dalibo_link_if_present(file_enum, consumed_lines)
+    # Look ahead to see if there are Dalibo links after the result block
+    begin
+      # Keep consuming blank lines and Dalibo 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?("[Dalibo]")
+          consumed_lines << file_enum.next
+        else
+          # Hit something that's not a blank line or Dalibo link, stop consuming
+          break
+        end
+      end
+    rescue StopIteration
+      # End of file reached, nothing more to consume
+    end
+  end
+end