yaml-converter 0.1.0

data/lib/yaml/converter/state_machine.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Yaml
+  module Converter
+    # Simple state machine to transform {Parser::Token} sequences into
+    # Markdown lines. Produces:
+    # - Title lines as plain paragraphs
+    # - A validation status line (formatted with date)
+    # - Fenced YAML blocks for YAML content
+    # - Blockquoted notes (outside fences)
+    class StateMachine
+      START_YAML = "```yaml"
+      END_YAML = "```"
+
+      # @param options [Hash]
+      # @option options [Symbol] :validation_status (:ok) Injected validation result (:ok or :fail)
+      # @option options [Integer] :max_line_length (70)
+      # @option options [Boolean] :truncate (true)
+      # @option options [Symbol] :margin_notes (:auto)
+      # @option options [Date] :current_date (Date.today)
+      def initialize(options = {})
+        @options = options
+        @validate_status = options.fetch(:validation_status, :ok)
+        @max_len = options.fetch(:max_line_length, 70)
+        @truncate = options.fetch(:truncate, true)
+        @margin_notes = options.fetch(:margin_notes, :auto)
+        @current_date = options[:current_date] || Date.today
+      end
+
+      # Apply stateful transformations to tokens and emit Markdown lines.
+      #
+      # @param tokens [Array<Parser::Token>]
+      # @return [Array<String>] Output lines (without trailing newlines)
+      def apply(tokens)
+        out = []
+        state = :text
+        tokens.each do |t|
+          case t.type
+          when :blank
+            out << ""
+          when :title
+            close_yaml(out, state)
+            out << t.text
+            out << ""
+            state = :text
+          when :validation
+            close_yaml(out, state)
+            date = @current_date.strftime("%d/%m/%Y")
+            status_str = ((@validate_status == :ok) ? "OK" : "Fail")
+            out << "YAML validation:*#{status_str}* on #{date}"
+            out << ""
+            state = :text
+          when :separator
+            # ignore
+          when :dash_heading
+            close_yaml(out, state)
+            out << "# #{t.text}".strip
+            out << ""
+            state = :text
+          when :yaml_line
+            state = open_yaml(out, state)
+            line = t.text
+            if @truncate && line.length > @max_len
+              line = line[0...(@max_len - 2)] + ".."
+            end
+            out << line
+          when :note
+            if @margin_notes != :ignore
+              was_yaml = (state == :yaml)
+              close_yaml(out, state)
+              out << "" if out.last && out.last != ""
+              out << "> NOTE: #{t.text}"
+              out << ""
+              state = was_yaml ? open_yaml(out, :text) : :text
+            end
+          else
+            # unknown token type: ignore gracefully
+          end
+        end
+        close_yaml(out, state)
+        out
+      end
+
+      private
+
+      # Open a fenced YAML block if not already inside one.
+      # @param out [Array<String>]
+      # @param state [Symbol]
+      # @return [Symbol] new state
+      def open_yaml(out, state)
+        if state != :yaml
+          out << "" if out.last && out.last != ""
+          out << START_YAML
+          :yaml
+        else
+          state
+        end
+      end
+
+      # Close a fenced YAML block if currently inside one.
+      # @param out [Array<String>]
+      # @param state [Symbol]
+      # @return [void]
+      def close_yaml(out, state)
+        if state == :yaml
+          out << END_YAML
+          # removed trailing blank line to keep legacy expected output pattern
+        end
+      end
+    end
+  end
+end

data/lib/yaml/converter/streaming_emitter.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "parser"
+
+module Yaml
+  module Converter
+    # StreamingEmitter converts YAML to Markdown incrementally.
+    # It mirrors MarkdownEmitter + StateMachine behavior while writing to an IO target.
+    # Intended for very large inputs to avoid building all output in memory.
+    class StreamingEmitter
+      START_YAML = "```yaml"
+      END_YAML = "```"
+
+      # @param options [Hash] same normalized options as Config.resolve
+      # @param io [#<<] destination IO (e.g., File) that receives lines with "\n"
+      def initialize(options, io)
+        @options = options
+        @io = io
+        @validation_status = :ok
+        @state = :text
+        @_last_line_blank = nil
+      end
+
+      # Set the validation status used when injecting the validation status line.
+      # @param status [Symbol] :ok or :fail
+      # @return [void]
+      def set_validation_status(status)
+        @validation_status = status
+      end
+
+      # Stream-convert an input file path to the configured IO.
+      # @param input_path [String]
+      # @return [void]
+      def emit_file(input_path)
+        File.open(input_path, "r") do |f|
+          f.each_line do |raw|
+            emit_line(raw)
+          end
+        end
+        close_yaml
+        emit_footer if @options[:emit_footer]
+      end
+
+      private
+
+      def max_len
+        @options.fetch(:max_line_length)
+      end
+
+      def truncate?
+        @options.fetch(:truncate)
+      end
+
+      def margin_notes
+        @options.fetch(:margin_notes)
+      end
+
+      def current_date
+        @options[:current_date] || Date.today
+      end
+
+      def emit_line(raw)
+        # Reuse Parser for correctness on a per-line basis
+        parser = (@_parser ||= Parser.new(@options))
+        tokens = parser.tokenize([raw])
+        tokens.each { |t| handle_token(t) }
+      end
+
+      def handle_token(t)
+        case t.type
+        when :blank
+          write_line("")
+        when :title
+          close_yaml
+          write_line(t.text)
+          write_line("")
+        when :validation
+          close_yaml
+          date = current_date.strftime("%d/%m/%Y")
+          status_str = ((@validation_status == :ok) ? "OK" : "Fail")
+          write_line("YAML validation:*#{status_str}* on #{date}")
+          write_line("")
+        when :separator
+          # ignore
+        when :dash_heading
+          close_yaml
+          write_line("# #{t.text}".strip)
+          write_line("")
+        when :yaml_line
+          open_yaml
+          line = t.text
+          if truncate? && line.length > max_len
+            line = line[0...(
+              max_len - 2
+            )] + ".."
+          end
+          write_line(line)
+        when :note
+          return if margin_notes == :ignore
+          was_yaml = (@state == :yaml)
+          close_yaml
+          write_line("") if last_line_not_blank?
+          write_line("> NOTE: #{t.text}")
+          write_line("")
+          open_yaml if was_yaml
+        else
+          # ignore unknown types
+        end
+      end
+
+      def open_yaml
+        return if @state == :yaml
+        write_line("") if last_line_not_blank?
+        write_line(START_YAML)
+        @state = :yaml
+      end
+
+      def close_yaml
+        if @state == :yaml
+          write_line(END_YAML)
+          @state = :text
+        end
+      end
+
+      def emit_footer
+        write_line("---- ")
+        write_line("")
+        write_line("Produced by [yaml-converter](https://github.com/kettle-rb/yaml-converter)")
+      end
+
+      def write_line(s)
+        if @wrote_any_line
+          @io << "\n"
+        end
+        @io << s
+        @wrote_any_line = true
+        @_last_line_blank = (s == "")
+      end
+
+      def last_line_not_blank?
+        @_last_line_blank == false
+      end
+    end
+  end
+end

data/lib/yaml/converter/validation.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Yaml
+  module Converter
+    # YAML validation helpers.
+    #
+    # This module provides simple validation by attempting to parse input using
+    # Psych.safe_load with a minimal, safe set of options. It does not raise on
+    # failure; instead it returns a structured Hash indicating status and error.
+    #
+    # @see .validate_string
+    # @see .validate_file
+    module Validation
+      module_function
+
+      # Validate a YAML string by attempting to load it safely via Psych.
+      #
+      # Uses Psych.safe_load with:
+      # - permitted_classes: []
+      # - permitted_symbols: []
+      # - aliases: true
+      #
+      # @param yaml_string [String] the YAML content to validate
+      # @return [Hash] a result hash
+      # @return [Hash] [
+      #   { status: :ok, error: nil } when parsing succeeds,
+      #   { status: :fail, error: Exception } when parsing fails
+      # ]
+      # @example Success
+      #   Yaml::Converter::Validation.validate_string("foo: bar")
+      #   #=> { status: :ok, error: nil }
+      # @example Failure
+      #   Yaml::Converter::Validation.validate_string(": : :")
+      #   #=> { status: :fail, error: #<Psych::SyntaxError ...> }
+      def validate_string(yaml_string)
+        # Psych.safe_load requires permitted classes for complex YAML; for our purposes,
+        # allow basic types and symbols off.
+        Psych.safe_load(
+          yaml_string,
+          permitted_classes: [],
+          permitted_symbols: [],
+          aliases: true,
+        )
+        {status: :ok, error: nil}
+      rescue StandardError => e
+        {status: :fail, error: e}
+      end
+
+      # Validate a YAML file by reading it and delegating to {.validate_string}.
+      #
+      # @param path [String] filesystem path to a YAML file
+      # @return [Hash] see {.validate_string}
+      # @example
+      #   Yaml::Converter::Validation.validate_file("config.yml")
+      #   #=> { status: :ok, error: nil }
+      def validate_file(path)
+        content = File.read(path)
+        validate_string(content)
+      end
+    end
+  end
+end

data/lib/yaml/converter/version.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Yaml
+  module Converter
+    # Namespace for version information.
+    module Version
+      # The gem version.
+      # @return [String]
+      VERSION = "0.1.0"
+    end
+    # The gem version, exposed at the root of the Yaml::Converter namespace.
+    # @return [String]
+    VERSION = Version::VERSION
+  end
+end

data/lib/yaml/converter.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+# External dependencies
+require "version_gem"
+
+# This library
+require_relative "converter/version"
+require_relative "converter/config"
+require_relative "converter/validation"
+require_relative "converter/markdown_emitter"
+require_relative "converter/streaming_emitter"
+
+module Yaml
+  module Converter
+    # Base error class for all yaml-converter specific exceptions.
+    class Error < StandardError; end
+    # Raised when provided arguments (paths, extensions, etc.) are invalid.
+    class InvalidArgumentsError < Error; end
+    # Raised when a requested renderer is not available or implemented.
+    class RendererUnavailableError < Error; end
+    # Raised when pandoc rendering is requested but pandoc cannot be located.
+    class PandocNotFoundError < Error; end
+
+    module_function
+
+    # Convert a YAML string into Markdown with optional validation & notes extraction.
+    #
+    # @param yaml_string [String] Raw YAML content (with optional inline `#note:` annotations or validation marker line)
+    # @param options [Hash, Config::DEFAULTS] User overrides for configuration (see {Yaml::Converter::Config::DEFAULTS})
+    # @option options [Boolean] :validate (true) Whether to attempt YAML parsing and inject validation status.
+    # @option options [Integer] :max_line_length (70) Maximum line length before truncation.
+    # @option options [Boolean] :truncate (true) Whether to truncate overly long lines.
+    # @option options [Symbol] :margin_notes (:auto) How to handle notes (:auto, :inline, :ignore).
+    # @option options [Date] :current_date (Date.today) Deterministic date injection for specs.
+    # @return [String] Markdown document including fenced YAML and extracted notes.
+    # @example Simple conversion
+    #   Yaml::Converter.to_markdown("foo: 1 #note: first")
+    def to_markdown(yaml_string, options: {})
+      opts = Config.resolve(options)
+      emitter = MarkdownEmitter.new(opts)
+      if opts[:validate]
+        validation = Validation.validate_string(yaml_string)
+        status = (validation && validation[:status] == :ok) ? :ok : :fail
+        emitter.set_validation_status(status)
+      end
+      emitter.emit(yaml_string.lines).join("\n")
+    end
+
+    # Stream a YAML file to Markdown into an IO target.
+    # Automatically injects validation status if enabled.
+    # @param input_path [String]
+    # @param io [#<<]
+    # @param options [Hash]
+    # @return [void]
+    def to_markdown_streaming(input_path, io, options: {})
+      opts = Config.resolve(options)
+      emitter = StreamingEmitter.new(opts, io)
+      if opts[:validate]
+        validation = Validation.validate_file(input_path)
+        status = (validation && validation[:status] == :ok) ? :ok : :fail
+        emitter.set_validation_status(status)
+      end
+      emitter.emit_file(input_path)
+      nil
+    end
+
+    # Validate a YAML string returning a structured status.
+    #
+    # @param yaml_string [String]
+    # @return [Hash{Symbol=>Object}] Hash with :status (:ok|:fail) and :error (Exception or nil)
+    # @example
+    #   Yaml::Converter.validate("foo: bar") #=> { status: :ok, error: nil }
+    def validate(yaml_string)
+      Validation.validate_string(yaml_string)
+    end
+
+    # Convert a YAML file to a target format determined by the output extension.
+    #
+    # Supported extensions (Phase 1): .md, .html, .pdf (native), .docx (pandoc).
+    # Other formats may be produced via pandoc when :use_pandoc is true.
+    #
+    # @param input_path [String] Path to existing .yaml source file.
+    # @param output_path [String] Destination file (extension decides rendering strategy).
+    # @param options [Hash] See {#to_markdown} plus pandoc/pdf specific keys.
+    # @option options [Boolean] :use_pandoc (false) Enable pandoc for non-native conversions.
+    # @option options [Array<String>] :pandoc_args (["-N", "--toc"]) Extra pandoc CLI args.
+    # @option options [String,nil] :pandoc_path (nil) Explicit pandoc binary path (auto-detected if nil).
+    # @option options [Boolean] :pdf_two_column_notes (false) Layout notes beside YAML in PDF.
+    # @option options [Boolean] :streaming (false) Force streaming mode for markdown conversion.
+    # @option options [Integer] :streaming_threshold_bytes (5_000_000) Auto-enable streaming over this size when not forced.
+    # @return [Hash] { status: Symbol, output_path: String, validation: Hash }
+    # @raise [InvalidArgumentsError] if input is missing or an invalid extension is requested.
+    # @raise [PandocNotFoundError] when pandoc rendering requested & missing.
+    # @raise [RendererUnavailableError] for unsupported formats.
+    # @example HTML conversion
+    #   Yaml::Converter.convert(input_path: "blueprint.yaml", output_path: "blueprint.html", options: {})
+    def convert(input_path:, output_path:, options: {})
+      raise InvalidArgumentsError, "input file not found: #{input_path}" unless File.exist?(input_path)
+
+      ext = File.extname(output_path)
+      if ext == ".yaml"
+        raise InvalidArgumentsError, "Output must not be .yaml"
+      end
+
+      opts = Config.resolve(options)
+      yaml_string = nil
+
+      if File.exist?(output_path) && ENV["KETTLE_TEST_SILENT"] != "true"
+        warn("Overwriting existing file: #{output_path}")
+      end
+
+      auto_stream = !opts[:streaming] && File.size?(input_path) && File.size(input_path) >= opts[:streaming_threshold_bytes]
+
+      if ext == ".md" || ext == ""
+        # Direct markdown output path: stream to file for large inputs
+        File.open(output_path, "w") do |io|
+          if opts[:streaming] || auto_stream
+            to_markdown_streaming(input_path, io, options: opts)
+          else
+            yaml_string = File.read(input_path)
+            io.write(to_markdown(yaml_string, options: opts))
+          end
+        end
+        validation_result = if opts[:validate]
+          yaml_string ? Validation.validate_string(yaml_string) : Validation.validate_file(input_path)
+        else
+          {status: :ok, error: nil}
+        end
+        return {status: :ok, output_path: output_path, validation: validation_result}
+      end
+
+      # For non-markdown outputs, we still produce an intermediate markdown string.
+      yaml_string = File.read(input_path) if yaml_string.nil?
+      markdown = to_markdown(yaml_string, options: opts)
+
+      # Helper lambda to build standard success response
+      success = lambda do
+        {status: :ok, output_path: output_path, validation: (opts[:validate] ? Validation.validate_string(yaml_string) : {status: :ok, error: nil})}
+      end
+
+      case ext
+      when ".html"
+        require "kramdown"
+        require "kramdown-parser-gfm"
+
+        body_html = Kramdown::Document.new(markdown, input: "GFM").to_html
+        note_style = ""
+        if markdown.include?("> NOTE:")
+          note_style = "<style>.yaml-note{font-style:italic;color:#555;margin-left:1em;}</style>\n"
+          body_html = body_html.gsub("<blockquote>", '<blockquote class="yaml-note">')
+        end
+        html = <<~HTML
+          <!DOCTYPE html>
+          <html>
+          <head>
+          <meta charset="utf-8">
+          #{note_style}</head>
+          <body>
+          #{body_html}
+          </body>
+          </html>
+        HTML
+        File.write(output_path, html)
+        success.call
+      when ".pdf"
+        if opts[:use_pandoc]
+          tmp_md = output_path + ".md"
+          File.write(tmp_md, markdown)
+          require_relative "converter/renderer/pandoc_shell"
+          ok = Renderer::PandocShell.render(md_path: tmp_md, out_path: output_path, pandoc_path: opts[:pandoc_path], args: opts[:pandoc_args])
+          File.delete(tmp_md) if File.exist?(tmp_md)
+          raise PandocNotFoundError, "pandoc not found in PATH" unless ok
+        else
+          require_relative "converter/renderer/pdf_prawn"
+          ok = Renderer::PdfPrawn.render(markdown: markdown, out_path: output_path, options: opts)
+          raise RendererUnavailableError, "PDF rendering failed" unless ok
+        end
+        success.call
+      when ".docx"
+        tmp_md = output_path + ".md"
+        File.write(tmp_md, markdown)
+        require_relative "converter/renderer/pandoc_shell"
+        pandoc_path = Renderer::PandocShell.which("pandoc")
+        if pandoc_path
+          ok = Renderer::PandocShell.render(md_path: tmp_md, out_path: output_path, pandoc_path: pandoc_path, args: [])
+          File.delete(tmp_md) if File.exist?(tmp_md)
+          raise RendererUnavailableError, "pandoc failed to generate DOCX" unless ok
+          success.call
+        else
+          File.delete(tmp_md) if File.exist?(tmp_md)
+          raise RendererUnavailableError, "DOCX requires pandoc; install pandoc or use .md/.html/.pdf"
+        end
+      else
+        tmp_md = output_path + ".md"
+        File.write(tmp_md, markdown)
+        if opts[:use_pandoc]
+          require_relative "converter/renderer/pandoc_shell"
+          ok = Renderer::PandocShell.render(md_path: tmp_md, out_path: output_path, pandoc_path: opts[:pandoc_path], args: opts[:pandoc_args])
+          File.delete(tmp_md) if File.exist?(tmp_md)
+          raise PandocNotFoundError, "pandoc not found in PATH" unless ok
+          success.call
+        else
+          raise RendererUnavailableError, "Renderer for #{ext} not implemented. Pass use_pandoc: true or use .md/.html/.pdf."
+        end
+      end
+    end
+  end
+end
+
+# Extend the Version with VersionGem::Basic to provide semantic version helpers.
+Yaml::Converter::Version.class_eval do
+  extend VersionGem::Basic
+end

data/sig/yaml/converter/config.rbs

@@ -0,0 +1,13 @@
+module Yaml
+  module Converter
+    module Config
+      DEFAULTS: { max_line_length: Integer, truncate: bool, margin_notes: Symbol, validate: bool, use_pandoc: bool, pandoc_args: Array[String], pandoc_path: String? , html_theme: Symbol, pdf_page_size: String, pdf_margin: Array[Integer], pdf_title_font_size: Integer, pdf_body_font_size: Integer, pdf_yaml_font_size: Integer, pdf_two_column_notes: bool, current_date: untyped, emit_footer: bool, streaming: bool, streaming_threshold_bytes: Integer }
+      ENV_MAP: { max_line_length: String, truncate: String, margin_notes: String, validate: String, use_pandoc: String, pdf_page_size: String, pdf_title_font_size: String, pdf_body_font_size: String, pdf_yaml_font_size: String, pdf_two_column_notes: String, emit_footer: String, streaming: String, streaming_threshold_bytes: String }
+      BOOLEAN_KEYS: Array[Symbol]
+
+      def self.resolve: (?Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+      def self.normalize: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+      def self.coerce_env_value: (Symbol, String) -> untyped
+    end
+  end
+end

data/sig/yaml/converter/markdown_emitter.rbs

@@ -0,0 +1,14 @@
+module Yaml
+  module Converter
+    class MarkdownEmitter
+      START_YAML: String
+      END_YAML: String
+      VALIDATED_STR: String
+      NOTE_STR: String
+
+      def initialize: (Yaml::Converter::options options) -> void
+      def set_validation_status: (Symbol) -> void
+      def emit: (Array[String]) -> Array[String]
+    end
+  end
+end

data/sig/yaml/converter/streaming_emitter.rbs

@@ -0,0 +1,13 @@
+module Yaml
+  module Converter
+    class StreamingEmitter
+      START_YAML: String
+      END_YAML: String
+
+      def initialize: (Yaml::Converter::options options, untyped io) -> void
+      def set_validation_status: (Symbol) -> void
+      def emit_file: (String input_path) -> void
+    end
+  end
+end
+

data/sig/yaml/converter/validation.rbs

@@ -0,0 +1,9 @@
+module Yaml
+  module Converter
+    module Validation
+      def self.validate_string: (String) -> { status: Symbol, error: Exception? }
+      def self.validate_file: (String) -> { status: Symbol, error: Exception? }
+    end
+  end
+end
+

data/sig/yaml/converter.rbs

@@ -0,0 +1,43 @@
+module Yaml
+  module Converter
+    VERSION: String
+
+    class Error < ::StandardError
+    end
+
+    class InvalidArgumentsError < Error
+    end
+
+    class RendererUnavailableError < Error
+    end
+
+    class PandocNotFoundError < Error
+    end
+
+    type options = {
+      max_line_length: Integer,
+      truncate: bool,
+      margin_notes: Symbol,
+      validate: bool,
+      use_pandoc: bool,
+      pandoc_args: Array[String],
+      pandoc_path: String?,
+      html_theme: Symbol,
+      pdf_page_size: String,
+      pdf_margin: Array[Integer],
+      pdf_title_font_size: Integer,
+      pdf_body_font_size: Integer,
+      pdf_yaml_font_size: Integer,
+      pdf_two_column_notes: bool,
+      current_date: untyped,
+      emit_footer: bool,
+      streaming: bool,
+      streaming_threshold_bytes: Integer
+    }
+
+    def self.to_markdown: (String yaml_string, ?options: options) -> String
+    def self.to_markdown_streaming: (String input_path, untyped io, ?options: options) -> void
+    def self.validate: (String yaml_string) -> { status: Symbol, error: Exception? }
+    def self.convert: (input_path: String, output_path: String, ?options: options) -> { status: Symbol, output_path: String, validation: { status: Symbol, error: Exception? } }
+  end
+end