etassia 0.1.0

data/lib/etassia/cli.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Etassia
+  # Command-line interface for etassia.
+  #
+  # Provides commands for rendering diagrams to SVG and
+  # managing diagram types.
+  class Cli < Thor
+    def self.exit_on_failure?
+      true
+    end
+
+    desc "render [FILE]", "Render a diagram to SVG"
+    long_desc <<~DESC
+      Renders a diagram from FILE or stdin to SVG format.
+
+      If FILE is not provided or is "-", reads from stdin.
+      Output is written to stdout by default, or to the file specified
+      with --output.
+
+      Examples:
+        etassia render diagram.mmd
+        etassia render diagram.mmd --output diagram.svg
+        etassia render diagram.mmd --theme dark
+        etassia render diagram.mmd --theme /path/to/custom-theme.yml
+        cat diagram.mmd | etassia render
+        etassia render --verbose diagram.mmd
+        etassia render --notation mermaid diagram.txt
+        etassia render --require ./my_notation.rb diagram.my
+    DESC
+    method_option :output,
+                  aliases: "-o",
+                  type: :string,
+                  desc: "Output file path (default: stdout)"
+    method_option :format,
+                  aliases: "-f",
+                  type: :string,
+                  default: "svg",
+                  desc: "Output format (only svg supported)"
+    method_option :theme,
+                  aliases: "-t",
+                  type: :string,
+                  desc: "Theme name or path to theme file " \
+                        "(default, dark, light, high_contrast)"
+    method_option :verbose,
+                  aliases: "-v",
+                  type: :boolean,
+                  default: false,
+                  desc: "Enable verbose output"
+    method_option :notation,
+                  type: :string,
+                  desc: "Notation to use (default: detected from the " \
+                        "file extension, then the source)"
+    method_option :require,
+                  aliases: "-r",
+                  type: :string,
+                  repeatable: true,
+                  desc: "Load a notation file before rendering " \
+                        "(repeatable, like ruby -r)"
+    def render(file = "-")
+      require_relative "commands/render"
+      Commands::RenderCommand.new(file, options).run
+    rescue *EXHAUSTION_ERRORS, StandardError => e
+      # `RenderCommand#run` builds the theme (a hostile `--theme` YAML
+      # file) and reads the input file BEFORE `Engine#render` is ever
+      # called, so both sit outside the engine's own widened rescue.
+      # `EXHAUSTION_ERRORS` are not `StandardError`, so without naming
+      # them here the CLI process goes down raw instead of printing an
+      # error and exiting 1, exactly like an unguarded `batch` used to.
+      handle_error(e)
+    end
+
+    desc "types", "List supported diagram types"
+    long_desc <<~DESC
+      Lists all diagram types currently supported by etassia.
+
+      Examples:
+        etassia types
+        etassia types --require ./my_notation.rb
+    DESC
+    method_option :require,
+                  aliases: "-r",
+                  type: :string,
+                  repeatable: true,
+                  desc: "Load a notation file first (repeatable, like ruby -r)"
+    def types
+      require_relative "commands/types"
+      Commands::TypesCommand.new(options).run
+    rescue StandardError => e
+      handle_error(e)
+    end
+
+    desc "batch", "Batch render multiple diagrams"
+    long_desc <<~DESC
+      Renders all diagrams in a directory to SVG format.
+
+      Recursively finds every file with a registered notation's extension
+      (or only --notation's) in the input directory and generates
+      corresponding SVG files in the output directory.
+
+      Examples:
+        etassia batch --input docs/diagrams --output docs/images
+        etassia batch -i diagrams -o output --theme dark
+        etassia batch -i docs -o output -v
+        etassia batch -i docs -o output --notation mermaid
+    DESC
+    method_option :input,
+                  aliases: "-i",
+                  type: :string,
+                  default: ".",
+                  desc: "Input directory or file"
+    method_option :output,
+                  aliases: "-o",
+                  type: :string,
+                  default: "output",
+                  desc: "Output directory"
+    method_option :theme,
+                  aliases: "-t",
+                  type: :string,
+                  desc: "Theme name or path to theme file"
+    method_option :verbose,
+                  aliases: "-v",
+                  type: :boolean,
+                  default: false,
+                  desc: "Enable verbose output"
+    method_option :notation,
+                  type: :string,
+                  desc: "Notation to use (default: detected from the " \
+                        "file extension, then the source)"
+    method_option :require,
+                  aliases: "-r",
+                  type: :string,
+                  repeatable: true,
+                  desc: "Load a notation file before rendering " \
+                        "(repeatable, like ruby -r)"
+    def batch
+      require_relative "commands/batch"
+      command = Commands::BatchCommand.new(options)
+      command.run
+      exit 1 unless command.success?
+    rescue StandardError => e
+      handle_error(e)
+    end
+
+    desc "version", "Show etassia version"
+    long_desc <<~DESC
+      Displays the current version of etassia.
+
+      Examples:
+        etassia version
+    DESC
+    def version
+      require_relative "commands/version"
+      Commands::VersionCommand.new(options).run
+    rescue StandardError => e
+      handle_error(e)
+    end
+
+    # Make version available as --version flag
+    map %w[--version -V] => :version
+
+    private
+
+    # Handles errors and exits with appropriate code.
+    #
+    # @param error [StandardError, SystemStackError, NoMemoryError]
+    #   the error to handle
+    # @return [void]
+    def handle_error(error)
+      warn "Error: #{error.message}"
+      report_verbose_error(error) if options[:verbose]
+      exit 1
+    end
+
+    def report_verbose_error(error)
+      # `backtrace` is nil when the VM fails an allocation before it can
+      # even build one -- `NoMemoryError` from `File.read` or a hostile
+      # `--theme` reaches this method through the rescue above, and
+      # `--verbose` on that failure must not itself crash the CLI.
+      warn error.backtrace&.join("\n")
+      diagnostics = ErrorReport.cause_diagnostics(error)
+      warn diagnostics unless diagnostics.empty?
+    end
+  end
+end

data/lib/etassia/commands/batch.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "notation_loader"
+
+module Etassia
+  module Commands
+    # Batch command for rendering multiple diagrams.
+    #
+    # Processes entire directories of diagram files and generates
+    # corresponding SVG output files.
+    class BatchCommand
+      attr_reader :options
+
+      def initialize(options = {})
+        @options = options
+        @stats = { success: 0, failed: 0, errors: [] }
+      end
+
+      # Execute the batch rendering command.
+      #
+      # @return [void]
+      def run
+        input_path = options[:input] || "."
+        output_path = options[:output] || "output"
+        print_header(input_path, output_path)
+        NotationLoader.load_all(options[:require])
+        files = find_diagram_files(input_path)
+        return print_empty(input_path) if files.empty?
+
+        render_batch(files, input_path, output_path)
+      end
+
+      # Whether every item rendered without error. Checked after #run, not
+      # returned by it: #run's own contract (print the summary, survive a
+      # bad file) is unrelated to whether the caller should exit non-zero,
+      # and a boolean return on a method named `run` reads as a lie about
+      # what it does.
+      #
+      # @return [Boolean] true if nothing failed (including a run that
+      #   found no files at all)
+      def success?
+        @stats[:failed].zero?
+      end
+
+      private
+
+      def render_batch(files, input_path, output_path)
+        print_file_count(files)
+        FileUtils.mkdir_p(output_path)
+        process_files(files, input_path, output_path)
+        print_summary
+      end
+
+      def print_header(input_path, output_path)
+        puts "Etassia Batch Renderer"
+        puts "=" * 60
+        puts "Input:  #{input_path}"
+        puts "Output: #{output_path}"
+        puts "Theme:  #{options[:theme] || 'default'}"
+        puts
+      end
+
+      def print_empty(input_path)
+        puts "No diagram files found in: #{input_path}"
+      end
+
+      def print_file_count(files)
+        puts "Found #{files.length} diagram files"
+        puts
+      end
+
+      def process_files(files, input_path, output_path)
+        files.each_with_index do |file, index|
+          process_file(file, input_path, output_path, index + 1, files.length)
+        end
+      end
+
+      def find_diagram_files(path)
+        if File.directory?(path)
+          extensions = batch_extensions
+          Dir.glob(File.join(path, "**", "*")).select do |file|
+            File.file?(file) && extensions.include?(File.extname(file).downcase)
+          end
+        elsif File.file?(path)
+          [path]
+        else
+          []
+        end
+      end
+
+      # Every registered notation's extensions, or only `--notation`'s.
+      def batch_extensions
+        return Notation.extensions unless options[:notation]
+
+        Notation.fetch(options[:notation]).extensions
+      end
+
+      # Only a registered extension is swapped; any other name is kept.
+      def output_name(relative)
+        extension = File.extname(relative)
+        return relative unless Notation.extensions.include?(extension.downcase)
+
+        "#{relative.delete_suffix(extension)}.svg"
+      end
+
+      # `-i` names either a directory or a single file (`find_mermaid_files`
+      # accepts both, and it's documented on the CLI). The directory case
+      # strips `input_base` off the front of `file` to get a path relative
+      # to it; a single file IS `input_base`, so that same subtraction
+      # leaves '', turning `output_file` into the output directory itself.
+      def relative_path_for(file, input_base)
+        return File.basename(file) if File.file?(input_base)
+
+        file.sub(/^#{Regexp.escape(input_base)}\/?/, "")
+      end
+
+      def process_file(file, input_base, output_base, current, total)
+        relative = relative_path_for(file, input_base)
+        output_file = File.join(output_base, output_name(relative))
+        print "[#{current}/#{total}] #{relative}... "
+        process_render(file, output_file, relative)
+      end
+
+      def process_render(file, output_file, relative)
+        render_file(file, output_file)
+        record_success
+      rescue *Etassia::EXHAUSTION_ERRORS, StandardError => e
+        record_failure(relative, e)
+      end
+
+      def render_file(file, output_file)
+        # Raw bytes, as `RenderCommand#read_input` reads them: a text-mode
+        # read would apply the locale's encodings before `Source` sees it.
+        source = File.binread(file)
+        svg = Etassia.render(source, **render_options(file))
+        FileUtils.mkdir_p(File.dirname(output_file))
+        File.binwrite(output_file, svg)
+      end
+
+      def render_options(file)
+        {
+          theme: options[:theme], verbose: options[:verbose], path: file,
+          notation: options[:notation]
+        }
+      end
+
+      def record_success
+        @stats[:success] += 1
+        puts "✅"
+      end
+
+      def record_failure(relative, error)
+        @stats[:failed] += 1
+        @stats[:errors] << { file: relative, error: error.message }
+        puts "❌ #{error.class.name}"
+        print_verbose_failure(error) if options[:verbose]
+      end
+
+      def print_verbose_failure(error)
+        puts "   #{error.message}"
+        # Printed, never stored: `@stats[:errors]` outlives the whole run,
+        # and a cause's trace is what must not accumulate there.
+        diagnostics = Etassia::ErrorReport.cause_diagnostics(error)
+        return if diagnostics.empty?
+
+        puts diagnostics.lines.map { |line| "   #{line}" }.join
+      end
+
+      def print_summary
+        print_summary_header
+        print_summary_counts
+        print_errors if @stats[:failed].positive?
+        print_success_rate
+      end
+
+      def print_summary_header
+        puts "\n#{'=' * 60}"
+        puts "BATCH RENDERING SUMMARY"
+        puts "=" * 60
+      end
+
+      def print_summary_counts
+        puts "✅ Success: #{@stats[:success]}"
+        puts "❌ Failed:  #{@stats[:failed]}"
+        puts "   Total:   #{@stats[:success] + @stats[:failed]}"
+      end
+
+      def print_errors
+        puts "\nErrors:"
+        @stats[:errors].first(5).each do |error|
+          puts "  #{error[:file]}: #{error[:error].lines.first.strip}"
+        end
+        print_extra_error_count
+        puts "\nUse --verbose to see full error details"
+      end
+
+      def print_extra_error_count
+        return unless @stats[:errors].length > 5
+
+        puts "  ... and #{@stats[:errors].length - 5} more errors"
+      end
+
+      def print_success_rate
+        rate = (@stats[:success].to_f / (@stats[:success] + @stats[:failed]))
+        puts "\nSuccess rate: #{(rate * 100).round(1)}%"
+      end
+    end
+  end
+end

data/lib/etassia/commands/notation_loader.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Commands
+    # Loads the files named by `--require`, exactly as `ruby -r` would: a
+    # notation registers itself while its file loads.
+    module NotationLoader
+      module_function
+
+      # @param features [Array<String>, String, nil] feature names or paths
+      # @return [void]
+      # @raise [ArgumentError] when a feature cannot be loaded
+      def load_all(features)
+        Array(features).each do |feature|
+          require feature
+        rescue LoadError
+          raise ArgumentError, "Cannot load notation: #{feature}"
+        end
+      end
+    end
+  end
+end

data/lib/etassia/commands/render.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "notation_loader"
+
+module Etassia
+  module Commands
+    # Command to render diagrams to SVG.
+    class RenderCommand
+      attr_reader :file, :options
+
+      # Creates a new render command.
+      #
+      # @param file [String] input file path or '-' for stdin
+      # @param options [Hash] command options
+      def initialize(file, options = {})
+        @file = file
+        @options = options
+      end
+
+      # Executes the render command.
+      #
+      # @return [void]
+      def run
+        validate_format!
+
+        NotationLoader.load_all(options[:require])
+        write_output(render_source(read_input))
+      end
+
+      private
+
+      def render_source(source)
+        engine = Engine.new(verbose: options[:verbose], theme: options[:theme])
+        engine.render(source, path: path_hint, notation: options[:notation])
+      end
+
+      # The extension is a notation hint, so only a real file offers one.
+      def path_hint
+        file unless file == "-" || file.nil?
+      end
+
+      # Validates the output format option.
+      #
+      # @return [void]
+      # @raise [ArgumentError] if format is not supported
+      def validate_format!
+        return if options[:format] == "svg"
+
+        raise ArgumentError,
+              "Unsupported format: #{options[:format]}. " \
+              "Only SVG format is currently supported."
+      end
+
+      # Reads input from file or stdin.
+      #
+      # Text-mode reads tag their result with the locale's encoding and, under
+      # `ruby -E ext:int`, transcode it first. The bytes are read raw instead
+      # and `Source` reads them as UTF-8, as mmdc does; otherwise a UTF-8 file
+      # under `LC_ALL=en_US.ISO8859-1` is drawn as mojibake.
+      #
+      # @return [String] Mermaid source code
+      def read_input
+        if file == "-" || file.nil?
+          $stdin.binmode.read
+        else
+          File.binread(file)
+        end
+      rescue Errno::ENOENT
+        raise ArgumentError, "File not found: #{file}"
+      rescue Errno::EACCES
+        raise ArgumentError, "Permission denied: #{file}"
+      end
+
+      # Writes output to file or stdout.
+      #
+      # @param svg [String] SVG content
+      # @return [void]
+      def write_output(svg)
+        if options[:output]
+          File.binwrite(options[:output], svg)
+          puts "SVG written to #{options[:output]}" if options[:verbose]
+        else
+          print_svg(svg)
+        end
+      rescue Errno::EACCES
+        raise ArgumentError,
+              "Permission denied writing to: #{options[:output]}"
+      end
+
+      # UTF-8 to UTF-8, so the stream does not transcode to the locale's
+      # encoding, or raise on a character it lacks.
+      def print_svg(svg)
+        $stdout.set_encoding(Encoding::UTF_8, Encoding::UTF_8)
+        $stdout.write(svg, "\n")
+      end
+    end
+  end
+end

data/lib/etassia/commands/types.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "notation_loader"
+
+module Etassia
+  module Commands
+    # Command to list supported diagram types.
+    class TypesCommand
+      attr_reader :options
+
+      # Creates a new types command.
+      #
+      # @param options [Hash] command options
+      def initialize(options = {})
+        @options = options
+      end
+
+      # Executes the types command.
+      #
+      # @return [void]
+      def run
+        NotationLoader.load_all(options[:require])
+        puts "Supported diagram types:"
+
+        Notation.plugins.each do |notation|
+          puts
+          puts "#{notation.id}:"
+          notation.types.each { |type| puts "  #{type}" }
+        end
+      end
+    end
+  end
+end

data/lib/etassia/commands/version.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Commands
+    # Command to display the gem version.
+    class VersionCommand
+      attr_reader :options
+
+      # Creates a new version command.
+      #
+      # @param options [Hash] command options
+      def initialize(options = {})
+        @options = options
+      end
+
+      # Executes the version command.
+      #
+      # @return [void]
+      def run
+        puts "etassia version #{Etassia::VERSION}"
+      end
+    end
+  end
+end

data/lib/etassia/corpus_type_names.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Etassia
+  # The one table relating spec/mermaid directory names to the type symbols
+  # in {Etassia::Notation::Mermaid::TYPES}. A directory with no registered
+  # type (diagrams that must fail detection) maps to nil.
+  #
+  # Read by {Etassia::DiagramRegistry.corpus_directories} and by
+  # Etassia::Corpus.registry_type in tasks/corpus.rake. One directory names
+  # each type.
+  module CorpusTypeNames
+    DIRECTORIES = {
+      "architecture" => :architecture,
+      "block" => :block,
+      "c4" => :c4,
+      "class_diagram" => :class_diagram,
+      "er_diagram" => :er_diagram,
+      "error" => :error,
+      "flowchart" => :flowchart,
+      "gantt" => :gantt,
+      "gitgraph" => :git_graph,
+      "info" => :info,
+      "kanban" => :kanban,
+      "mindmap" => :mindmap,
+      "packet" => :packet,
+      "pie" => :pie,
+      "quadrant" => :quadrant,
+      "radar" => :radar,
+      "requirement" => :requirement,
+      "sankey" => :sankey,
+      "sequence" => :sequence,
+      "state_diagram" => :state_diagram,
+      "timeline" => :timeline,
+      "treemap" => :treemap,
+      "unknown" => nil,
+      "user_journey" => :user_journey,
+      "xychart" => :xychart,
+    }.freeze
+
+    class << self
+      # @return [Symbol, nil] the registry type for a corpus directory
+      def registry_type(directory)
+        DIRECTORIES[directory]
+      end
+
+      # @return [Array<String>] corpus directories holding a registry type
+      def directories_for(type)
+        DIRECTORIES.select { |_, name| name == type }.keys
+      end
+    end
+  end
+end