markdown-run 0.1.9 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d87607302aa1e1f4b95d1da2b1857f792d34b3d3d7985299db1a6730d7f49b57
-  data.tar.gz: d10dd3193558ce3c59770bd5b9ba7f73e8a5f3459cea9482deeff7bfc21333a1
+  metadata.gz: 1139e0ccb6ed1b5b4ee2cef44cf067c83fc8a92ad750eae2e256725282534b68
+  data.tar.gz: 8887f778eaec56e6bdbb84d0a48f8db82fbd52cabbcdea01c48f4cffb5ff410b
 SHA512:
-  metadata.gz: 1bbf13073d892d85165b1396a78ec6f274cb75a941fd8dc50f21b4c9636572966c2983f001851286fcb14531eed0a3d2177df42f8d1851e98f62175c5b83c78e
-  data.tar.gz: 97f9f35734c1440d8b21cc62176a65458bce898cb223368c65af4e0888f4bbd986dc6e403a382f982561dc6ad572f4f9c24c3f2f41d8c0aa6186cc6d5d25f656
+  metadata.gz: 6656d86bf179be5a044a95ccbc1a9c11e68642a35ed2ffa99138dc0de653ed4b2e176a9763f08b765d409ec232e4b9eda4779b166c97b7304ed156a48b147c93
+  data.tar.gz: 3f8771ece0365e9a1c7073a6d749d41570776b59e9cbe0c38383516cce9cf0261a2ba287aadb30278ee0cf72e859fe4b4cb072fa89294bc3a525700fdec5ff9c

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+## [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)
+
 ## [0.1.9] - 2025-06-02
 
 - mermaid codeblocks

data/README.md

@@ -57,8 +57,21 @@ example vscode keybinding
 
 - `run=true` or `run=false` to control whether a code block should be executed at all. `run=true` is the default if not specified
 - `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
 
-Options can be combined. If `run=false` is specified, the code block will not execute regardless of the `rerun` setting.
+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.
+
+### Standalone Option Syntax
+
+Options can also be specified using standalone syntax without explicit `=true`:
+
+- `run` is equivalent to `run=true`
+- `rerun` is equivalent to `rerun=true`
+- `result` is equivalent to `result=true`
+- `explain` is equivalent to `explain=true`
+
+Explicit assignments (e.g., `run=false`) take precedence over standalone options.
 
 Examples:
 
@@ -66,7 +79,7 @@ Examples:
 console.log("This will not execute at all");
 ```
 
-```js rerun=true
+```js rerun
 console.log("This will re-execute even if result exists");
 ```
 
@@ -74,6 +87,23 @@ console.log("This will re-execute even if result exists");
 console.log("This will execute only if no result exists");
 ```
 
+```ruby result=false run
+puts "This executes but the result block is hidden"
+```
+
+```psql explain
+SELECT * FROM users WHERE id = 1;
+```
+
+```psql explain=true
+EXPLAIN (ANALYZE) SELECT * FROM large_table;
+```
+
+```psql result=false explain
+SELECT * FROM large_table;
+-- This will execute the explain query and show the Dalibo link but hide the result block
+```
+
 ### Mermaid diagrams
 
 Mermaid blocks generate SVG files and insert markdown image tags:

data/lib/code_block_parser.rb

@@ -42,6 +42,14 @@ class CodeBlockParser
     parse_boolean_option(options_string, "rerun", false)
   end
 
+  def parse_explain_option(options_string)
+    parse_boolean_option(options_string, "explain", false)
+  end
+
+  def parse_result_option(options_string)
+    parse_boolean_option(options_string, "result", true)
+  end
+
   private
 
   def resolve_language(lang)
@@ -51,10 +59,19 @@ class CodeBlockParser
   def parse_boolean_option(options_string, option_name, default_value)
     return default_value unless options_string
 
-    # Match option=true or option=false
-    match = options_string.match(/#{option_name}\s*=\s*(true|false)/i)
-    return default_value unless match
+    # First, check for explicit option=true/false assignments (highest priority)
+    explicit_match = options_string.match(/#{option_name}\s*=\s*(true|false)/i)
+    if explicit_match
+      return explicit_match[1].downcase == "true"
+    end
+
+    # If no explicit assignment, check for standalone option (e.g., "rerun")
+    standalone_match = options_string.match(/\b#{option_name}\b(?!\s*=)/i)
+    if standalone_match
+      return true
+    end
 
-    match[1].downcase == "true"
+    # If neither found, return default value
+    default_value
   end
 end

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)
-    new.execute(code_content, lang, temp_dir, input_file_path)
+  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)
   end
 
-  def execute(code_content, lang, temp_dir, input_file_path = nil)
+  def execute(code_content, lang, temp_dir, input_file_path = nil, explain = false)
     lang_key = lang.downcase
     lang_config = SUPPORTED_LANGUAGES[lang_key]
 
@@ -15,8 +15,8 @@ class CodeExecutor
 
     warn "Executing #{lang_key} code block..."
 
-    result = execute_with_config(code_content, lang_config, temp_dir, lang_key, input_file_path)
-    process_execution_result(result, lang_config, lang_key)
+    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)
   end
 
   private
@@ -26,23 +26,23 @@ class CodeExecutor
     "ERROR: Unsupported language: #{lang}"
   end
 
-  def execute_with_config(code_content, lang_config, temp_dir, lang_key, input_file_path = nil)
+  def execute_with_config(code_content, lang_config, temp_dir, lang_key, input_file_path = nil, explain = 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)
+      execute_with_temp_file(code_content, cmd_lambda, temp_file_suffix, temp_dir, lang_key, input_file_path, explain)
     else
-      execute_direct_command(code_content, cmd_lambda)
+      execute_direct_command(code_content, cmd_lambda, explain)
     end
   end
 
-  def execute_with_temp_file(code_content, cmd_lambda, temp_file_suffix, temp_dir, lang_key, input_file_path = nil)
+  def execute_with_temp_file(code_content, cmd_lambda, temp_file_suffix, temp_dir, lang_key, input_file_path = nil, explain = 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)
+      command_to_run, exec_options = cmd_lambda.call(code_content, temp_file.path, input_file_path, explain)
 
       # Extract output_path if present (for mermaid)
       output_path = exec_options.delete(:output_path) if exec_options.is_a?(Hash)
@@ -58,19 +58,21 @@ class CodeExecutor
     result
   end
 
-  def execute_direct_command(code_content, cmd_lambda)
-    command_to_run, exec_options = cmd_lambda.call(code_content, nil)
+  def execute_direct_command(code_content, cmd_lambda, explain = false)
+    command_to_run, exec_options = cmd_lambda.call(code_content, nil, nil, explain)
     captured_stdout, captured_stderr, captured_status_obj = Open3.capture3(command_to_run, **exec_options)
     { stdout: captured_stdout, stderr: captured_stderr, status: captured_status_obj }
   end
 
-  def process_execution_result(result, lang_config, lang_key)
+  def process_execution_result(result, lang_config, lang_key, explain = 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)
     end
 
     result_output
@@ -118,7 +120,7 @@ class CodeExecutor
     # If the SVG is in a subdirectory, include the directory in the path
     output_dir = File.dirname(output_path)
     svg_filename = File.basename(output_path)
-    
+
     # Check if SVG is in a subdirectory (new behavior) or same directory (fallback)
     parent_dir = File.dirname(output_dir)
     if File.basename(output_dir) != File.basename(parent_dir)
@@ -128,10 +130,83 @@ class CodeExecutor
       # SVG is in same directory (fallback behavior)
       relative_path = svg_filename
     end
-    
+
     warn "Generated Mermaid SVG: #{relative_path}"
 
     # Return markdown image tag instead of typical result content
     "![Mermaid Diagram](#{relative_path})"
   end
+
+  def handle_psql_explain_result(result_output)
+    require 'json'
+    require 'net/http'
+    require 'uri'
+
+    # Try to parse the result as JSON (EXPLAIN output)
+    begin
+      # Clean up the result output and try to parse as JSON
+      json_data = JSON.parse(result_output.strip)
+
+      # Submit plan to Dalibo via POST request
+      dalibo_url = submit_plan_to_dalibo(JSON.generate(json_data))
+
+      if dalibo_url
+        # Return a special format that the markdown processor can parse
+        "DALIBO_LINK:#{dalibo_url}\n#{result_output.strip}"
+      else
+        # If submission failed, just return the original output
+        result_output
+      end
+    rescue JSON::ParserError
+      # If it's not valid JSON, just return the original output
+      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
+
+      # 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}"
+          end
+          location
+        else
+          nil
+        end
+      else
+        warn "Failed to submit plan to Dalibo: #{response.code} #{response.message}"
+        nil
+      end
+    rescue => e
+      warn "Error submitting plan to Dalibo: #{e.message}"
+      nil
+    end
+  end
 end

data/lib/execution_decider.rb

@@ -3,10 +3,12 @@ require_relative "enum_helper"
 class ExecutionDecider
   include EnumHelper
 
-  def initialize(current_block_run, current_block_rerun, current_block_lang)
+  def initialize(current_block_run, current_block_rerun, current_block_lang, current_block_explain = 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_result = current_block_result
   end
 
   def decide(file_enum, result_block_regex_method)
@@ -19,6 +21,8 @@ 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)
+      handle_immediate_dalibo_link(file_enum)
     else
       execute_without_existing_result
     end
@@ -44,12 +48,23 @@ 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
+      peek2 = peek_next_line(file_enum)
+    end
 
     if line_matches_pattern?(peek2, expected_header_regex)
-      handle_result_after_blank_line(file_enum, consumed_blank_line)
+      handle_result_after_blank_lines(file_enum, consumed_blank_line, additional_blanks)
+    elsif @current_block_explain && is_dalibo_link?(peek2)
+      handle_dalibo_after_blank_lines(file_enum, consumed_blank_line, additional_blanks)
     else
-      execute_with_blank_line(consumed_blank_line)
+      execute_with_blank_lines(consumed_blank_line, additional_blanks)
     end
   end
 
@@ -61,6 +76,24 @@ class ExecutionDecider
     end
   end
 
+  def handle_result_after_blank_lines(file_enum, consumed_blank_line, additional_blanks)
+    if @current_block_rerun
+      execute_with_consumed_result_and_blanks(file_enum, consumed_blank_line, additional_blanks)
+    else
+      skip_with_blanks_and_result(file_enum, consumed_blank_line, additional_blanks)
+    end
+  end
+
+  def handle_dalibo_after_blank_lines(file_enum, consumed_blank_line, additional_blanks)
+    # For explain result=false, always replace existing Dalibo links
+    # For explain result=true, follow normal rerun logic
+    if should_auto_replace_dalibo_link? || @current_block_rerun
+      execute_with_consumed_dalibo_and_blanks(file_enum, consumed_blank_line, additional_blanks)
+    else
+      skip_with_blanks_and_dalibo(file_enum, consumed_blank_line, additional_blanks)
+    end
+  end
+
   def execute_with_consumed_result(file_enum)
     consumed_lines = [file_enum.next]
     { execute: true, consumed_lines: consumed_lines, consume_existing: true }
@@ -83,10 +116,98 @@ class ExecutionDecider
     { execute: true, blank_line: consumed_blank_line }
   end
 
+  def execute_with_blank_lines(consumed_blank_line, additional_blanks)
+    { execute: true, blank_line: consumed_blank_line, additional_blanks: additional_blanks }
+  end
+
+  def execute_with_consumed_result_and_blanks(file_enum, consumed_blank_line, additional_blanks)
+    consumed_lines = [consumed_blank_line] + additional_blanks + [file_enum.next]
+    { execute: true, consumed_lines: consumed_lines, blank_line: consumed_blank_line, consume_existing: true }
+  end
+
+  def skip_with_blanks_and_result(file_enum, consumed_blank_line, additional_blanks)
+    lines_to_pass = [consumed_blank_line] + additional_blanks + [file_enum.next]
+    { execute: false, lines_to_pass_through: lines_to_pass }
+  end
+
+  def execute_with_consumed_dalibo_and_blanks(file_enum, consumed_blank_line, additional_blanks)
+    consumed_lines = [consumed_blank_line] + additional_blanks
+    consume_dalibo_links(file_enum, consumed_lines)
+    { execute: true, consumed_lines: consumed_lines, blank_line: consumed_blank_line, consume_existing_dalibo: true }
+  end
+
+  def skip_with_blanks_and_dalibo(file_enum, consumed_blank_line, additional_blanks)
+    consumed_lines = [consumed_blank_line] + additional_blanks
+    consume_dalibo_links(file_enum, consumed_lines)
+    { execute: false, lines_to_pass_through: consumed_lines, dalibo_content: true }
+  end
+
   def execute_without_existing_result
     { execute: true }
   end
 
+  def handle_immediate_dalibo_link(file_enum)
+    # For explain result=false, always replace existing Dalibo links
+    # For explain result=true, follow normal rerun logic
+    if should_auto_replace_dalibo_link? || @current_block_rerun
+      execute_with_consumed_dalibo(file_enum)
+    else
+      skip_with_existing_dalibo(file_enum)
+    end
+  end
+
+  def handle_dalibo_after_blank_line(file_enum, consumed_blank_line)
+    # For explain result=false, always replace existing Dalibo links
+    # For explain result=true, follow normal rerun logic
+    if should_auto_replace_dalibo_link? || @current_block_rerun
+      execute_with_consumed_dalibo_and_blank(file_enum, consumed_blank_line)
+    else
+      skip_with_blank_and_dalibo(file_enum, consumed_blank_line)
+    end
+  end
+
+  def execute_with_consumed_dalibo(file_enum)
+    consumed_lines = []
+    consume_dalibo_links(file_enum, consumed_lines)
+    { execute: true, consumed_lines: consumed_lines, consume_existing_dalibo: true }
+  end
+
+  def skip_with_existing_dalibo(file_enum)
+    consumed_lines = []
+    consume_dalibo_links(file_enum, consumed_lines)
+    { execute: false, lines_to_pass_through: consumed_lines, dalibo_content: true }
+  end
+
+  def execute_with_consumed_dalibo_and_blank(file_enum, consumed_blank_line)
+    consumed_lines = [consumed_blank_line]
+    consume_dalibo_links(file_enum, consumed_lines)
+    { execute: true, consumed_lines: consumed_lines, blank_line: consumed_blank_line, consume_existing_dalibo: true }
+  end
+
+  def skip_with_blank_and_dalibo(file_enum, consumed_blank_line)
+    consumed_lines = [consumed_blank_line]
+    consume_dalibo_links(file_enum, consumed_lines)
+    { execute: false, lines_to_pass_through: consumed_lines, dalibo_content: true }
+  end
+
+  def consume_dalibo_links(file_enum, consumed_lines)
+    # 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
+      else
+        break
+      end
+    end
+  end
+
+  def is_dalibo_link?(line)
+    line&.start_with?("**Dalibo Visualization:**")
+  end
+
   def line_matches_pattern?(line, pattern)
     line && line.match?(pattern)
   end
@@ -94,4 +215,11 @@ class ExecutionDecider
   def is_blank_line?(line)
     line && line.strip == ""
   end
+
+  def should_auto_replace_dalibo_link?
+    # Auto-replace Dalibo links when using explain 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
+  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) {
+  command: ->(_code_content, temp_file_path, input_file_path = nil, explain = false) {
     # Check if bun is available
     bun_exists = system("command -v bun > /dev/null 2>&1")
     if bun_exists
@@ -16,22 +16,32 @@ JS_CONFIG = {
 }.freeze
 
 SQLITE_CONFIG = {
-  command: ->(code_content, temp_file_path, input_file_path = nil) { [ "sqlite3 #{temp_file_path}", { stdin_data: code_content } ] },
+  command: ->(code_content, temp_file_path, input_file_path = nil, explain = 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) {
+    command: ->(code_content, _temp_file_path, input_file_path = nil, explain = 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
-      [ "psql -A -t -X", { stdin_data: code_content } ]
+
+      # Modify the SQL query if explain option is enabled
+      if explain
+        # 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*$/, '')
+        explained_query = "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) #{clean_query};"
+        [ "psql -A -t -X", { stdin_data: explained_query } ]
+      else
+        [ "psql -A -t -X", { stdin_data: code_content } ]
+      end
     }
   },
   "ruby" => {
-    command: ->(_code_content, temp_file_path, input_file_path = nil) {
+    command: ->(_code_content, temp_file_path, input_file_path = nil, explain = 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."
@@ -47,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) {
+    command: ->(_code_content, temp_file_path, input_file_path = nil, explain = 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."
@@ -57,7 +67,7 @@ SUPPORTED_LANGUAGES = {
     temp_file_suffix: ".sh"
   },
   "zsh" => {
-    command: ->(_code_content, temp_file_path, input_file_path = nil) {
+    command: ->(_code_content, temp_file_path, input_file_path = nil, explain = 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."
@@ -67,7 +77,7 @@ SUPPORTED_LANGUAGES = {
     temp_file_suffix: ".zsh"
   },
   "sh" => {
-    command: ->(_code_content, temp_file_path, input_file_path = nil) {
+    command: ->(_code_content, temp_file_path, input_file_path = nil, explain = 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."
@@ -77,7 +87,7 @@ SUPPORTED_LANGUAGES = {
     temp_file_suffix: ".sh"
   },
   "mermaid" => {
-    command: ->(code_content, temp_file_path, input_file_path = nil) {
+    command: ->(code_content, temp_file_path, input_file_path = nil, explain = 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"
@@ -87,11 +97,11 @@ SUPPORTED_LANGUAGES = {
       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)

data/lib/markdown/run/version.rb

@@ -2,6 +2,6 @@
 
 module Markdown
   module Run
-    VERSION = "0.1.9"
+    VERSION = "0.1.10"
   end
 end

data/lib/markdown_processor.rb

@@ -16,6 +16,8 @@ class MarkdownProcessor
     @current_code_content = ""
     @current_block_rerun = false
     @current_block_run = true
+    @current_block_explain = false
+    @current_block_result = true
     @frontmatter_parser = FrontmatterParser.new
     @code_block_parser = CodeBlockParser.new(@frontmatter_parser)
   end
@@ -103,6 +105,14 @@ class MarkdownProcessor
     @code_block_parser.parse_run_option(options_string)
   end
 
+  def parse_explain_option(options_string)
+    @code_block_parser.parse_explain_option(options_string)
+  end
+
+  def parse_result_option(options_string)
+    @code_block_parser.parse_result_option(options_string)
+  end
+
   def handle_line(current_line, file_enum)
     case @state
     when :outside_code_block
@@ -153,6 +163,8 @@ class MarkdownProcessor
     @current_block_lang = resolve_language(lang)
     @current_block_rerun = parse_rerun_option(options_string)
     @current_block_run = parse_run_option(options_string)
+    @current_block_explain = parse_explain_option(options_string)
+    @current_block_result = parse_result_option(options_string)
     @state = :inside_code_block
     @current_code_content = ""
   end
@@ -171,19 +183,22 @@ class MarkdownProcessor
       # 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)
+      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)
+    decider = ExecutionDecider.new(@current_block_run, @current_block_rerun, @current_block_lang, @current_block_explain, @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
@@ -193,20 +208,45 @@ class MarkdownProcessor
     @output_lines << blank_line_before_new_result if blank_line_before_new_result
 
     if has_content?(@current_code_content)
-      result_output = CodeExecutor.execute(@current_code_content, @current_block_lang, @temp_dir, @input_file_path)
-      add_result_block(result_output, blank_line_before_new_result)
+      result_output = CodeExecutor.execute(@current_code_content, @current_block_lang, @temp_dir, @input_file_path, @current_block_explain)
+
+      # Check if result contains a Dalibo link for psql explain queries
+      dalibo_link, clean_result = extract_dalibo_link(result_output)
+
+      # 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)
+      end
+
+      # Always add Dalibo link if it exists, even when result=false
+      if dalibo_link
+        # Add appropriate spacing based on whether result block was shown
+        if @current_block_result
+          @output_lines << "#{dalibo_link}\n\n"
+        else
+          @output_lines << "\n#{dalibo_link}\n\n"
+        end
+      end
     else
       warn "Skipping empty code block for language '#{@current_block_lang}'."
     end
   end
 
-  def skip_and_pass_through_result(lines_to_pass_through, file_enum)
+  def skip_and_pass_through_result(lines_to_pass_through, file_enum, decision = 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."
       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."
+      @output_lines.concat(lines_to_pass_through)
+      # No additional consumption needed for Dalibo 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)
@@ -235,6 +275,9 @@ class MarkdownProcessor
     consume_block_lines(file_enum) do |line|
       consumed_lines << line
     end
+
+    # After consuming the result block, check if there's a Dalibo link to consume as well
+    consume_dalibo_link_if_present(file_enum, consumed_lines)
   end
 
   def consume_block_lines(file_enum)
@@ -254,9 +297,46 @@ class MarkdownProcessor
     @current_code_content = ""
     @current_block_rerun = false
     @current_block_run = true
+    @current_block_explain = false
+    @current_block_result = true
   end
 
   def stderr_has_content?(stderr_output)
     stderr_output && !stderr_output.strip.empty?
   end
+
+  def extract_dalibo_link(result_output)
+    # Check if the result contains a Dalibo link marker
+    if result_output.start_with?("DALIBO_LINK:")
+      lines = result_output.split("\n", 2)
+      dalibo_url = lines[0].sub("DALIBO_LINK:", "")
+      clean_result = lines[1] || ""
+      dalibo_link = "**Dalibo Visualization:** [View Query Plan](#{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 Visualization:**")
+          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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: markdown-run
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.1.10
 platform: ruby
 authors:
 - Aurélien Bottazini
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-02 00:00:00.000000000 Z
+date: 2025-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rcodetools