markdown-run 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 921255b90c33af932d6ac33284a24d4f0fc61b5fe3ec0afb45f912c8fcc6e678
-  data.tar.gz: 076f40ed6dc79bafbc7bdba3198f39fabf56754d74e1ef6bd38f451cc34ccafd
+  metadata.gz: 1139e0ccb6ed1b5b4ee2cef44cf067c83fc8a92ad750eae2e256725282534b68
+  data.tar.gz: 8887f778eaec56e6bdbb84d0a48f8db82fbd52cabbcdea01c48f4cffb5ff410b
 SHA512:
-  metadata.gz: 01c7168af16a7788b80acb43553f2ae81ee0a8d1dfe7bf7cf048a6c7a77a898257fb1308b277282d9494464189322eab67b164a8c694f0aa8437db8bc8654d36
-  data.tar.gz: 4f719733a2fbea191224f8c0fbcbb44f559d2d9bec1352f9d6c6caf851550593eb3622b2453cfdd584513d3b186f085157cf17cde5dfe61706f60a6d8b2e8050
+  metadata.gz: 6656d86bf179be5a044a95ccbc1a9c11e68642a35ed2ffa99138dc0de653ed4b2e176a9763f08b765d409ec232e4b9eda4779b166c97b7304ed156a48b147c93
+  data.tar.gz: 3f8771ece0365e9a1c7073a6d749d41570776b59e9cbe0c38383516cce9cf0261a2ba287aadb30278ee0cf72e859fe4b4cb072fa89294bc3a525700fdec5ff9c

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.3.5

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [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
+
 ## [0.1.8] - 2025-06-01
 
 - Added run option

data/README.md

@@ -16,6 +16,7 @@ Supported languages:
 - postgresql
 - bash
 - zsh
+- mermaid (generates SVG diagrams)
 
 ## Installation
 
@@ -56,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:
 
@@ -65,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");
 ```
 
@@ -73,6 +87,41 @@ 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:
+
+```mermaid
+graph TD
+    A[Start] --> B[Process]
+    B --> C[End]
+```
+
+This generates an SVG file in a directory named after the markdown file, with a filename that includes the markdown file's basename and a timestamp:
+
+- Directory: `my-document/` (if the markdown file is `my-document.md`)
+- Filename: `my-document-20250602-215507-a1289a799c29.svg`
+- Image tag: `![Mermaid Diagram](my-document/my-document-20250602-215507-a1289a799c29.svg)`
+
+Note: Requires `@mermaid-js/mermaid-cli` to be installed: `npm install -g @mermaid-js/mermaid-cli`
+
 ## Frontmatter
 
 You can add a yaml frontmatter to redefine code block behavior.

data/Rakefile

@@ -0,0 +1,22 @@
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+desc "Run flog complexity analysis on the entire project"
+task :flog do
+  puts "Running flog complexity analysis..."
+  system("flog lib/ exe/ test/")
+end
+
+desc "Run flog with detailed method breakdown"
+task :flog_detailed do
+  puts "Running detailed flog analysis..."
+  system("flog -d lib/ exe/ test/")
+end
+
+task default: :test

data/exe/markdown-run

@@ -1,443 +1,16 @@
 #!/usr/bin/env ruby
 
-require "tempfile"
-require "open3"
-require "fileutils"
-require "yaml"
-require_relative "../lib/language_configs"
+require_relative "../lib/markdown_run"
 
 # Script to process markdown files, execute code blocks based on language,
 # and insert their results back into the markdown.
 
-def stderr_has_content?(stderr_output)
-  stderr_output && !stderr_output.strip.empty?
-end
-
-def format_captured_output(captured_status_obj, captured_stderr, captured_stdout, lang_config)
-  result_output = captured_stdout
-  stderr_output = captured_stderr
-  exit_status = captured_status_obj.exitstatus
-
-  # JS-specific: Append stderr to result if execution failed and stderr has content
-  if lang_config && lang_config[:error_handling] == :js_specific && exit_status != 0 && stderr_has_content?(stderr_output)
-    result_output += "\nStderr:\n#{stderr_output.strip}"
-  end
-  return exit_status, result_output, stderr_output
-end
-
-def add_error_to_output(exit_status, lang_config, lang_key, result_output, stderr_output)
-  warn "Code execution failed for language '#{lang_key}' with status #{exit_status}."
-  warn "Stderr:\n#{stderr_output}" if stderr_has_content?(stderr_output)
-
-  is_js_error_already_formatted = lang_config && lang_config[:error_handling] == :js_specific && result_output.include?("Stderr:")
-  unless result_output.downcase.include?("error:") || is_js_error_already_formatted
-    error_prefix = "Execution failed (status: #{exit_status})."
-    error_prefix += " Stderr: #{stderr_output.strip}" if stderr_has_content?(stderr_output)
-    result_output = "#{error_prefix}\n#{result_output}"
-  end
-  result_output
-end
-
-def execute_code_block(code_content, lang, temp_dir)
-  captured_status_obj = nil
-
-  lang_key = lang.downcase # Normalize lang input for lookup
-  lang_config = SUPPORTED_LANGUAGES[lang_key]
-
-  if lang_config
-    exit_status = 0
-    warn "Executing #{lang_key} code block..." # Generic description
-    cmd_lambda = lang_config[:command]
-    temp_file_suffix = lang_config[:temp_file_suffix]
-
-    captured_stdout = nil
-    if temp_file_suffix # Needs a temporary file. Use lang_key as prefix.
-      Tempfile.create([ lang_key, temp_file_suffix ], temp_dir) do |temp_file|
-        temp_file.write(code_content)
-        temp_file.close
-        # Pass temp_file.path. Lambda decides if it needs code_content directly.
-        command_to_run, exec_options = cmd_lambda.call(code_content, temp_file.path)
-        captured_stdout, _, captured_status_obj = Open3.capture3(command_to_run, **exec_options)
-      end
-    else # Direct command execution (e.g., psql that takes stdin)
-      # Pass nil for temp_file_path. Lambda decides if it needs code_content.
-      command_to_run, exec_options = cmd_lambda.call(code_content, nil)
-      captured_stdout, captured_stderr, captured_status_obj = Open3.capture3(command_to_run, **exec_options)
-    end
-  else
-    warn "Unsupported language: #{lang}"
-    result_output = "ERROR: Unsupported language: #{lang}"
-    exit_status = 1 # Indicate an error
-    # captured_status_obj remains nil, so common assignments below won't run
-  end
-
-  if captured_status_obj
-    exit_status, result_output, stderr_output = format_captured_output(captured_status_obj, captured_stderr, captured_stdout, lang_config)
-  end
-
-  if exit_status != 0
-    result_output = add_error_to_output(exit_status, lang_config, lang_key, result_output, stderr_output)
-  end
-  result_output
-end
-
-class MarkdownProcessor
-  def initialize(temp_dir)
-    @temp_dir = temp_dir
-    @output_lines = []
-    @state = :outside_code_block
-    @current_block_lang = ""
-    @current_code_content = ""
-    @current_block_rerun = false
-    @current_block_run = true
-    @aliases = {}
-  end
-
-  def process_file(file_enum)
-    parse_frontmatter(file_enum)
-
-    loop do
-      current_line = get_next_line(file_enum)
-      break unless current_line
-
-      handle_line(current_line, file_enum)
-    end
-    @output_lines
-  end
-
-  private
-
-  def parse_frontmatter(file_enum)
-    first_line = peek_next_line(file_enum)
-    return unless first_line&.strip == "---"
-
-    # Consume the opening ---
-    @output_lines << file_enum.next
-    frontmatter_lines = []
-
-    loop do
-      line = get_next_line(file_enum)
-      break unless line
-
-      if line.strip == "---"
-        @output_lines << line
-        break
-      end
-
-      frontmatter_lines << line
-      @output_lines << line
-    end
-
-    return if frontmatter_lines.empty?
-
-    begin
-      frontmatter = YAML.safe_load(frontmatter_lines.join)
-      extract_aliases(frontmatter) if frontmatter.is_a?(Hash)
-    rescue YAML::SyntaxError => e
-      warn "Warning: Invalid YAML frontmatter: #{e.message}"
-    end
-  end
-
-  def extract_aliases(frontmatter)
-    markdown_run_config = frontmatter["markdown-run"]
-    return unless markdown_run_config.is_a?(Hash)
-
-    aliases = markdown_run_config["alias"]
-    return unless aliases.is_a?(Array)
-
-    aliases.each do |alias_config|
-      next unless alias_config.is_a?(Hash)
-
-      alias_config.each do |alias_name, target_lang|
-        @aliases[alias_name.to_s] = target_lang.to_s
-      end
-    end
-  end
-
-  def resolve_language(lang)
-    @aliases[lang] || lang
-  end
-
-  def ruby_style_result?(lang)
-    lang_config = SUPPORTED_LANGUAGES[lang]
-    lang_config && lang_config[:result_block_type] == "ruby"
-  end
-
-  def result_block_header(lang)
-    ruby_style_result?(lang) ? "```ruby RESULT\n" : "```RESULT\n"
-  end
-
-  def result_block_regex(lang)
-    ruby_style_result?(lang) ? /^```ruby\s+RESULT$/i : /^```RESULT$/i
-  end
-
-  def is_block_end?(line)
-    line.strip == "```"
-  end
-
-  def has_content?(content)
-    !content.strip.empty?
-  end
-
-  def add_result_block(result_output, blank_line_before_new_result)
-    @output_lines << "\n" if blank_line_before_new_result.nil?
-    @output_lines << result_block_header(@current_block_lang)
-    @output_lines << result_output
-    @output_lines << "\n" unless result_output.empty? || result_output.end_with?("\n")
-    @output_lines << "```\n\n"
-  end
-
-  def line_matches_pattern?(line, pattern)
-    line && line.match?(pattern)
-  end
-
-  def is_blank_line?(line)
-    line && line.strip == ""
-  end
-
-  def parse_rerun_option(options_string)
-    return false unless options_string
-    
-    # Match rerun=true or rerun=false
-    match = options_string.match(/rerun\s*=\s*(true|false)/i)
-    return false unless match
-    
-    match[1].downcase == "true"
-  end
-
-  def parse_run_option(options_string)
-    return true unless options_string
-    
-    # Match run=true or run=false
-    match = options_string.match(/run\s*=\s*(true|false)/i)
-    return true unless match
-    
-    match[1].downcase == "true"
-  end
-
-  def safe_enum_operation(file_enum, operation)
-    file_enum.send(operation)
-  rescue StopIteration
-    nil
-  end
-
-  def get_next_line(file_enum)
-    safe_enum_operation(file_enum, :next)
-  end
-
-  def peek_next_line(file_enum)
-    safe_enum_operation(file_enum, :peek)
-  end
-
-  def handle_line(current_line, file_enum)
-    case @state
-    when :outside_code_block
-      handle_outside_code_block(current_line, file_enum)
-    when :inside_code_block
-      handle_inside_code_block(current_line, file_enum)
-    when :inside_result_block
-      handle_inside_result_block(current_line, file_enum)
-    end
-  end
-
-  def handle_outside_code_block(current_line, file_enum)
-    if current_line.match?(/^```ruby\s+RESULT$/i)
-      handle_existing_ruby_result_block(current_line, file_enum)
-    elsif (match_data = current_line.match(/^```(\w+)(?:\s+(.*))?$/i))
-      lang = match_data[1].downcase
-      options_string = match_data[2]
-      resolved_lang = resolve_language(lang)
-      if SUPPORTED_LANGUAGES.key?(resolved_lang)
-        start_code_block(current_line, lang, options_string)
-      else
-        @output_lines << current_line
-      end
-    else
-      @output_lines << current_line
-    end
-  end
-
-  def handle_inside_code_block(current_line, file_enum)
-    if is_block_end?(current_line)
-      end_code_block(current_line, file_enum)
-    else
-      accumulate_code_content(current_line)
-    end
-  end
-
-  def handle_inside_result_block(current_line, file_enum)
-    @output_lines << current_line
-    if is_block_end?(current_line)
-      @state = :outside_code_block
-    end
-  end
-
-  def handle_existing_ruby_result_block(current_line, file_enum)
-    warn "Found existing '```ruby RESULT' block, passing through."
-    @output_lines << current_line
-    @state = :inside_result_block
-  end
-
-  def start_code_block(current_line, lang, options_string = nil)
-    @output_lines << current_line
-    @current_block_lang = resolve_language(lang)
-    @current_block_rerun = parse_rerun_option(options_string)
-    @current_block_run = parse_run_option(options_string)
-    @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)
-    end
-
-    reset_code_block_state
-  end
-
-  def decide_execution(file_enum)
-    # If run=false, skip execution entirely (no result block creation)
-    unless @current_block_run
-      return { execute: false, lines_to_pass_through: [] }
-    end
-
-    peek1 = peek_next_line(file_enum)
-    expected_header_regex = result_block_regex(@current_block_lang)
-
-    if line_matches_pattern?(peek1, expected_header_regex)
-      # If rerun=true, execute even if result block exists
-      if @current_block_rerun
-        # Consume the existing result block and execute
-        consumed_lines = [file_enum.next]
-        consume_existing_result_block(file_enum, consumed_lines)
-        return { execute: true, consumed_lines: consumed_lines }
-      else
-        return { execute: false, lines_to_pass_through: [file_enum.next] }
-      end
-    elsif is_blank_line?(peek1)
-      consumed_blank_line = file_enum.next
-      peek2 = peek_next_line(file_enum)
-
-      if line_matches_pattern?(peek2, expected_header_regex)
-        if @current_block_rerun
-          # Consume the blank line and existing result block, then execute
-          consumed_lines = [consumed_blank_line, file_enum.next]
-          consume_existing_result_block(file_enum, consumed_lines)
-          return { execute: true, consumed_lines: consumed_lines, blank_line: consumed_blank_line }
-        else
-          return { execute: false, lines_to_pass_through: [consumed_blank_line, file_enum.next] }
-        end
-      else
-        return { execute: true, blank_line: consumed_blank_line }
-      end
-    else
-      return { execute: true }
-    end
-  end
-
-  def execute_and_add_result(blank_line_before_new_result)
-    @output_lines << blank_line_before_new_result if blank_line_before_new_result
-
-    if has_content?(@current_code_content)
-      result_output = execute_code_block(@current_code_content, @current_block_lang, @temp_dir)
-      add_result_block(result_output, blank_line_before_new_result)
-    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)
-    # 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
-
-    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."
-
-    @output_lines.concat(lines_to_pass_through)
-
-    consume_result_block_content(file_enum)
-  end
-
-  def consume_result_block_content(file_enum)
-    begin
-      loop do
-        result_block_line = file_enum.next
-        @output_lines << result_block_line
-        break if is_block_end?(result_block_line)
-      end
-    rescue StopIteration
-      warn "Warning: End of file reached inside a skipped 'RESULT' block."
-    end
-  end
-
-  def consume_existing_result_block(file_enum, consumed_lines)
-    begin
-      loop do
-        result_block_line = file_enum.next
-        consumed_lines << result_block_line
-        break if is_block_end?(result_block_line)
-      end
-    rescue StopIteration
-      warn "Warning: End of file reached while consuming existing result block for rerun."
-    end
-  end
-
-  def reset_code_block_state
-    @state = :outside_code_block
-    @current_code_content = ""
-    @current_block_rerun = false
-    @current_block_run = true
-  end
-end
-
-def process_markdown_file_main(input_file_path)
-  unless File.exist?(input_file_path) && File.readable?(input_file_path)
-    warn "Error: Input file '#{input_file_path}' not found or not readable."
-    return false # Indicate failure
-  end
-
-  temp_dir = File.dirname(File.expand_path(input_file_path))
-  file_enum = File.foreach(input_file_path, chomp: false).to_enum
-
-  processor = MarkdownProcessor.new(temp_dir)
-  output_lines = processor.process_file(file_enum)
-
-  # Write the modified content back to the input file
-  Tempfile.create([ "md_exec_out_", File.extname(input_file_path) ], temp_dir) do |temp_output_file|
-    temp_output_file.write(output_lines.join(""))
-    temp_output_file.close
-    begin
-      FileUtils.mv(temp_output_file.path, input_file_path)
-    rescue Errno::EACCES, Errno::EXDEV
-      warn "Atomic move failed. Falling back to copy and delete."
-      FileUtils.cp(temp_output_file.path, input_file_path)
-      FileUtils.rm_f(temp_output_file.path)
-    end
-  end
-  warn "Markdown processing complete. Output written to #{input_file_path}"
-  true # Indicate success
-end
-
 if ARGV.empty?
-  puts "Running tests..."
-  require_relative "../test_markdown_exec"
+  puts "Usage: markdown-run <file.md>"
+  puts "Processes a markdown file and executes code blocks, inserting their results."
+  exit 1 unless $0 != __FILE__  # Don't exit when loaded as a library
 else
-  process_markdown_file_main(ARGV[0])
+  success = MarkdownRun.run_code_blocks(ARGV[0])
+  exit success ? 0 : 1 unless $0 != __FILE__  # Don't exit when loaded as a library
 end
 

data/lib/code_block_parser.rb

@@ -0,0 +1,77 @@
+require_relative "language_configs"
+
+class CodeBlockParser
+  # Code block header pattern: ```language options
+  CODE_BLOCK_START_PATTERN = /^```(\w+)(?:\s+(.*))?$/i
+  RUBY_RESULT_BLOCK_PATTERN = /^```ruby\s+RESULT$/i
+  BLOCK_END_PATTERN = "```"
+
+  def initialize(frontmatter_parser)
+    @frontmatter_parser = frontmatter_parser
+  end
+
+  def parse_code_block_header(line)
+    match_data = line.match(CODE_BLOCK_START_PATTERN)
+    return nil unless match_data
+
+    lang = match_data[1].downcase
+    options_string = match_data[2]
+    resolved_lang = resolve_language(lang)
+
+    {
+      original_lang: lang,
+      resolved_lang: resolved_lang,
+      options_string: options_string,
+      is_supported: SUPPORTED_LANGUAGES.key?(resolved_lang)
+    }
+  end
+
+  def is_ruby_result_block?(line)
+    line.match?(RUBY_RESULT_BLOCK_PATTERN)
+  end
+
+  def is_block_end?(line)
+    line.strip == BLOCK_END_PATTERN
+  end
+
+  def parse_run_option(options_string)
+    parse_boolean_option(options_string, "run", true)
+  end
+
+  def parse_rerun_option(options_string)
+    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)
+    @frontmatter_parser.resolve_language(lang)
+  end
+
+  def parse_boolean_option(options_string, option_name, default_value)
+    return default_value unless options_string
+
+    # 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
+
+    # If neither found, return default value
+    default_value
+  end
+end