elkrb 1.0.0 → 2.0.0

data/exe/elkrb

@@ -1,8 +1,42 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "bundler/setup"
+# Run from a source checkout, load THIS checkout. Without bundler/setup on the
+# path there is nothing else pointing at ../lib, so `require "elkrb"` would
+# quietly pick up an installed gem instead, or fail outright.
+lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib) if File.directory?(lib) && !$LOAD_PATH.include?(lib)
+
 require "elkrb"
 require "elkrb/cli"
 
-Elkrb::Cli.start(ARGV)
+begin
+  Elkrb::Cli.start(ARGV)
+rescue Elkrb::CommandFailed
+  # The command already tried to report itself; only the status is left to
+  # decide. Printing again here would duplicate the report in the usual case,
+  # and a report that failed to write once will not write now either.
+  exit 1
+rescue Thor::Error => e
+  # A usage error (unknown command, missing required argument, wrong arity)
+  # never reaches a command body, so CommandFailed is not what Cli.start
+  # raises for it -- Cli.start's own #start override always raises this
+  # instead of exiting, matching the entry point that is allowed to call
+  # exit being THIS file, not the library class.
+  #
+  # THOR_DEBUG=1 asks for the backtrace, which is Thor's own contract for this
+  # rescue; and the report goes to $stderr directly, NOT through `warn`, which
+  # `ruby -W0` silences -- a usage error must still be reported there.
+  raise if ENV["THOR_DEBUG"] == "1"
+
+  $stderr.puts e.message # rubocop:disable Style/StderrPuts -- the cop's own
+  # suggestion (`warn`) is the bug: `ruby -W0` silences `warn` and would
+  # re-introduce the silent usage error this rescue exists to fix.
+  $stderr.puts Elkrb::Cli.usage_hint(ARGV) # rubocop:disable Style/StderrPuts
+  exit 1
+rescue Errno::EPIPE
+  # A reader hanging up ends a SUCCESSFUL run (`elkrb layout big.json |
+  # head`), so this is the exit code a clean pipeline expects -- Cli.start's
+  # own #start override no longer calls `exit` for this itself.
+  exit 0
+end

data/lib/elkrb/atomic_destination.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tempfile"
+
+require_relative "errors"
+
+module Elkrb
+  # Commits a single-file result only after its producer completes.
+  class AtomicDestination
+    class << self
+      def write(destination, content)
+        generate(destination) { |scratch| File.binwrite(scratch, content) }
+      end
+
+      def generate(destination, require_nonempty: false, &producer)
+        destination = File.path(destination)
+        directory = File.dirname(destination)
+        FileUtils.mkdir_p(directory)
+
+        basename = [".elkrb-", File.extname(destination)]
+        Tempfile.create(basename, directory) do |file|
+          File.chmod(destination_mode(destination), file.path)
+          commit(file, destination, require_nonempty, &producer)
+        end
+      end
+
+      private
+
+      def commit(file, destination, require_nonempty)
+        scratch = file.path
+        file.close
+        result = yield scratch
+        validate_output!(scratch) if require_nonempty
+        File.rename(scratch, destination)
+        result
+      end
+
+      def validate_output!(scratch)
+        return if File.file?(scratch) && File.size(scratch).positive?
+
+        raise Error, "Output producer reported success but produced no output"
+      end
+
+      def destination_mode(destination)
+        File.stat(destination).mode & 0o777
+      rescue Errno::ENOENT
+        0o666 & ~File.umask
+      end
+    end
+  end
+  private_constant :AtomicDestination
+end

data/lib/elkrb/best_effort_write.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Pure Ruby port of the Eclipse Layout Kernel. This file reopens the namespace
+# only to hang an internal helper off it; the public API lives in lib/elkrb.rb.
+module Elkrb
+  # Only the write that emits the RESULT may decide the exit status. Every
+  # other write -- a progress line, a failure report, anything printed
+  # before or alongside the result -- is best-effort.
+  #
+  # Such a write can raise for reasons that have nothing to do with what it
+  # is reporting: the reader hung up (Errno::EPIPE), or the text holds bytes
+  # the stream cannot encode (ArgumentError). Either used to escape in place
+  # of whatever came after it -- and because Thor rescues EPIPE and calls
+  # exit(true), a caller lost both its result (or its error) AND its
+  # process, silently, at exit 0.
+  #
+  # This module used to be named FailureReport and cover only a report
+  # printed just before a raise. That was too narrow: a `--verbose` progress
+  # line is not a failure report, so it never went through `attempt`, and a
+  # dead stdout during a verbose run had the exact same silent-exit-0 defect
+  # this module exists to prevent. Any write that is not the result write
+  # must go through `attempt`, whether or not a raise follows it -- UNLESS
+  # the write cannot raise in the first place. `Kernel#warn` is the one
+  # exception in this codebase, for the way stderr actually goes dead here:
+  # a reader closing its end of a real pipe leaves `$stderr` pointing at the
+  # SAME IO object with a now-broken file descriptor (`$stderr.reopen`, or a
+  # subprocess's inherited fd closing under it) -- and measured directly,
+  # `warn` does not raise there, unlike `$stderr.puts`/`$stderr.write`. It
+  # does raise if `$stderr` itself is reassigned to a different broken IO
+  # object (`$stderr = other_io`), which is a test-harness shape, not
+  # anything a closed pipe does to a running process. `warn` call sites in
+  # this codebase are exempt by construction for the real failure mode, not
+  # by oversight.
+  module BestEffortWrite
+    module_function
+
+    # Returns the block's value, or nil if the write raised. Nothing reads
+    # the value today -- either execution continues past a swallowed write,
+    # or a raise that follows the call site is what matters.
+    def attempt
+      yield
+    rescue StandardError
+      nil
+    end
+  end
+  # Internal. Reachable by the bare name from anywhere lexically inside
+  # Elkrb, which is every call site there will be.
+  private_constant :BestEffortWrite
+end

data/lib/elkrb/cli/layout_flag_options.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "thor"
+
+require_relative "../options/registry"
+
+module Elkrb
+  class Cli < Thor
+    # The flags that become layout options, declared once for every command
+    # that lays out a graph. `extend` it into the Thor class and call
+    # `layout_flags` directly above the command's `def`: Thor attaches
+    # `option` declarations to the next method defined, so the call has to
+    # sit where the individual `option` lines would.
+    #
+    # LayoutFlags.apply turns the parsed flags into root-graph options. Enum
+    # values in the help text are read from the registry when the class is
+    # defined, so a value added there reaches `--help` without an edit here.
+    module LayoutFlagOptions
+      # No Thor default: an absent --algorithm must stay nil so the graph's
+      # own elk.algorithm can be read before falling back to layered.
+      ALGORITHM_DESC = "Layout algorithm to use (default: the graph's " \
+                       "own elk.algorithm, else layered)"
+
+      def layout_flags
+        option :algorithm, type: :string, desc: ALGORITHM_DESC
+        option :direction, type: :string, desc: enum_desc(
+          "Layout direction", "elk.direction",
+          "; applied by layered and mrtree algorithms"
+        )
+        option :edge_routing, type: :string,
+                              desc: enum_desc("Edge routing", "elk.edgeRouting")
+        numeric_flags
+      end
+
+      private
+
+      def numeric_flags
+        option :spacing, type: :numeric, desc: "Node spacing"
+        option :layer_spacing, type: :numeric,
+                               desc: "Layer spacing (for layered algorithm)"
+        %w[top bottom left right].each do |side|
+          option :"padding_#{side}", type: :numeric,
+                                     desc: "#{side.capitalize} padding"
+        end
+      end
+
+      # @param id [String] a canonical registry id with an enumerated value list
+      def enum_desc(label, id, suffix = "")
+        values = Options::Registry.all.fetch(id).fetch(:values)
+        "#{label}, one of #{values.join(', ')}#{suffix}"
+      end
+    end
+  end
+end

data/lib/elkrb/cli.rb

@@ -4,61 +4,97 @@ require "thor"
 require "json"
 require "yaml"
 
+require_relative "errors"
+require_relative "atomic_destination"
+require_relative "best_effort_write"
+require_relative "layout_flags"
+require_relative "cli/layout_flag_options"
+require_relative "options/resolver"
+
 module Elkrb
   # Command-line interface for elkrb
   #
   # Provides commands for laying out graphs from the command line.
-  # Supports JSON and YAML input/output formats.
+  # Supports JSON and YAML input/output formats, with an ELKT fallback
+  # for files whose extension isn't recognized.
   class Cli < Thor
+    # Do not restore Thor::Base#start's rescues here. `rescue Thor::Error`
+    # either exits the process or swallows the error depending on
+    # `exit_on_failure?`, and `rescue Errno::EPIPE; exit(true)` exits
+    # unconditionally with no config to suppress it -- so a reader hanging
+    # up on `layout | head` would kill a library caller. Dispatching
+    # directly lets both propagate as themselves; exe/elkrb, the one entry
+    # point allowed to exit, turns them into exit codes.
+    def self.start(given_args = ARGV, config = {})
+      config[:shell] ||= Thor::Base.shell.new
+      dispatch(nil, given_args.dup, nil, config)
+    end
+
+    # Never reached: the override above calls #dispatch directly rather
+    # than Thor::Base#start, so nothing here consults this. Thor emits a
+    # deprecation warning if it is left undefined, so it stays, set to the
+    # value that matches this class actually being a library.
+    def self.exit_on_failure? = false
+
+    # The line that follows a usage error: help for the command the user
+    # named, else for the CLI as a whole.
+    #
+    # @param argv [Array<String>] the arguments the CLI was started with
+    # @return [String]
+    def self.usage_hint(argv)
+      name = argv.first
+      known = name && all_commands.key?(normalize_command_name(name))
+      known ? "Try: elkrb help #{name}" : "Try: elkrb help"
+    end
+
+    YAML_EXTENSIONS = %w[.yml .yaml].freeze
+    private_constant :YAML_EXTENSIONS
+
+    extend LayoutFlagOptions
+
+    # A mistyped flag is an error, not a positional argument: without this
+    # `elkrb layout --bogus` tries to read a file named "--bogus".
+    check_unknown_options!
+
     class_option :verbose, type: :boolean, default: false,
                            desc: "Enable verbose output"
 
-    desc "layout FILE", "Layout a graph from a JSON or YAML file"
-    option :algorithm, type: :string, default: "layered",
-                       desc: "Layout algorithm to use"
+    desc "layout FILE", "Layout a graph from a JSON, YAML, or ELKT file"
     option :output, type: :string, aliases: "-o",
                     desc: "Output file (default: stdout)"
-    option :format, type: :string, default: "json",
-                    enum: %w[json yaml],
-                    desc: "Output format"
-    option :spacing, type: :numeric,
-                     desc: "Node spacing"
-    option :layer_spacing, type: :numeric,
-                           desc: "Layer spacing (for layered algorithm)"
-    option :padding_top, type: :numeric,
-                         desc: "Top padding"
-    option :padding_bottom, type: :numeric,
-                            desc: "Bottom padding"
-    option :padding_left, type: :numeric,
-                          desc: "Left padding"
-    option :padding_right, type: :numeric,
-                           desc: "Right padding"
+    option :format, type: :string, enum: %w[json yaml],
+                    desc: "Output format (default: from the --output " \
+                          "extension, .yml/.yaml for YAML, else json)"
+    layout_flags
     def layout(file)
       verbose_output "Loading graph from #{file}..."
 
       # Read input file
       graph_data = read_input_file(file)
 
-      # Build layout options
-      layout_options = build_layout_options
+      # Explicit flags go onto the root graph, where they outrank the file
+      graph = LayoutFlags.apply(graph_data, options)
 
-      verbose_output "Using algorithm: #{layout_options[:algorithm]}"
+      algorithm = Options::Resolver.new.get("elk.algorithm", graph)
+      verbose_output "Using algorithm: #{algorithm}"
 
       # Perform layout
-      result = Layout::LayoutEngine.layout(graph_data, layout_options)
+      result = Layout::LayoutEngine.layout(graph, {})
 
       # Output result
       output_result(result)
 
       verbose_output "Layout complete!"
     rescue StandardError => e
-      error_output "Error: #{e.message}"
-      exit 1
+      fail_command(e, "layout")
     end
 
     desc "algorithms", "List available layout algorithms"
+    option :json, type: :boolean, default: false,
+                  desc: "Print the list as JSON on stdout"
     def algorithms
       algos = Layout::LayoutEngine.known_layout_algorithms
+      return say(json_for_algorithms(algos)) if options[:json]
 
       say "Available Layout Algorithms:", :green
       say ""
@@ -73,27 +109,31 @@ module Elkrb
       end
     end
 
+    desc "options [ALGORITHM]",
+         "List layout options, or those one algorithm supports"
+    option :json, type: :boolean, default: false,
+                  desc: "Print the options as JSON on stdout"
+    def options_list(algorithm = nil)
+      require_relative "commands/options_command"
+      Commands::OptionsCommand.new(algorithm, options).run
+    rescue StandardError => e
+      fail_command(e, "options")
+    end
+    map "options" => :options_list
+
     desc "diagram FILE", "Create diagram from ELK graph file"
-    option :algorithm, type: :string, default: "layered",
-                       desc: "Layout algorithm to use"
-    option :direction, type: :string,
-                       desc: "Layout direction (e.g., DOWN, RIGHT)"
-    option :spacing, type: :numeric,
-                     desc: "Node spacing"
-    option :edge_routing, type: :string,
-                          desc: "Edge routing strategy"
     option :output, type: :string, aliases: "-o", required: true,
                     desc: "Output file path"
     option :format, type: :string,
                     desc: "Output format (auto-detected from extension)"
     option :preview, type: :boolean, default: false,
                      desc: "Open result in default viewer"
+    layout_flags
     def diagram(file)
       require_relative "commands/diagram_command"
       Commands::DiagramCommand.new(file, options).run
     rescue StandardError => e
-      error_output "Error: #{e.message}"
-      exit 1
+      fail_command(e, "diagram")
     end
 
     desc "convert FILE", "Convert between formats (JSON/YAML/DOT/ELKT)"
@@ -105,8 +145,7 @@ module Elkrb
       require_relative "commands/convert_command"
       Commands::ConvertCommand.new(file, options).run
     rescue StandardError => e
-      error_output "Error: #{e.message}"
-      exit 1
+      fail_command(e, "convert")
     end
 
     desc "render DOT_FILE", "Render DOT to image (requires Graphviz)"
@@ -120,8 +159,7 @@ module Elkrb
       require_relative "commands/render_command"
       Commands::RenderCommand.new(dot_file, options).run
     rescue StandardError => e
-      error_output "Error: #{e.message}"
-      exit 1
+      fail_command(e, "render")
     end
 
     desc "validate FILE", "Validate ELK graph structure"
@@ -131,8 +169,7 @@ module Elkrb
       require_relative "commands/validate_command"
       Commands::ValidateCommand.new(file, options).run
     rescue StandardError => e
-      error_output "Error: #{e.message}"
-      exit 1
+      fail_command(e, "validate")
     end
 
     desc "batch DIR", "Process multiple files in a directory"
@@ -140,14 +177,12 @@ module Elkrb
                         desc: "Output directory for generated files"
     option :format, type: :string, default: "svg",
                     desc: "Output format for all files"
-    option :algorithm, type: :string, default: "layered",
-                       desc: "Layout algorithm to use"
+    layout_flags
     def batch(directory)
       require_relative "commands/batch_command"
       Commands::BatchCommand.new(directory, options).run
     rescue StandardError => e
-      error_output "Error: #{e.message}"
-      exit 1
+      fail_command(e, "batch")
     end
 
     desc "version", "Show elkrb version"
@@ -158,47 +193,28 @@ module Elkrb
     private
 
     def read_input_file(file)
-      require_relative "graph/graph"
-      content = File.read(file)
-
-      case File.extname(file).downcase
-      when ".json"
-        Elkrb::Graph::Graph.from_json(content)
-      when ".yml", ".yaml"
-        Elkrb::Graph::Graph.from_yaml(content)
-      else
-        # Try JSON first, then YAML
-        begin
-          Elkrb::Graph::Graph.from_json(content)
-        rescue JSON::ParserError
-          Elkrb::Graph::Graph.from_yaml(content)
-        end
-      end
+      require_relative "format_sniffer"
+      Elkrb::FormatSniffer.read(File.read(file), File.extname(file).downcase)
     end
 
-    def build_layout_options
-      opts = { algorithm: options[:algorithm] }
+    # --format wins; without it the --output extension decides, because
+    # `--output result.yml` asking for YAML is the one reading that cannot
+    # surprise anyone.
+    def output_format
+      return options[:format] if options[:format]
 
-      # Add spacing options
-      opts[:spacing_node_node] = options[:spacing] if options[:spacing]
-      opts[:layer_spacing] = options[:layer_spacing] if options[:layer_spacing]
-
-      # Add padding options
-      if options[:padding_top] || options[:padding_bottom] ||
-          options[:padding_left] || options[:padding_right]
-        opts[:padding] = {
-          top: options[:padding_top] || 12,
-          bottom: options[:padding_bottom] || 12,
-          left: options[:padding_left] || 12,
-          right: options[:padding_right] || 12,
-        }
-      end
+      extension = File.extname(options[:output].to_s).downcase
+      YAML_EXTENSIONS.include?(extension) ? "yaml" : "json"
+    end
 
-      opts
+    def json_for_algorithms(algos)
+      keys = %i[id name description category supports_hierarchy
+                supported_options]
+      JSON.generate("algorithms" => algos.map { |algo| algo.slice(*keys) })
     end
 
     def output_result(result)
-      output = case options[:format]
+      output = case output_format
                when "yaml"
                  result.to_yaml
                else
@@ -206,19 +222,76 @@ module Elkrb
                end
 
       if options[:output]
-        File.write(options[:output], output)
+        AtomicDestination.write(options[:output], output)
         verbose_output "Output written to #{options[:output]}"
       else
         say output
       end
     end
 
+    # Best-effort: this is a progress line, not the result. On a closed
+    # stderr it must not take the command down with it -- see
+    # Elkrb::BestEffortWrite for why a dead stream here used to mean
+    # SystemExit(0) with the real work never attempted.
+    #
+    # RC10: a progress line is not the result, so it never belongs on
+    # stdout next to the JSON. `say_error` is Thor's stderr counterpart to
+    # `say` and keeps the same colour helper.
     def verbose_output(message)
-      say message, :yellow if options[:verbose]
+      return unless options[:verbose]
+
+      BestEffortWrite.attempt { say_error message, :yellow }
     end
 
     def error_output(message)
-      say message, :red
+      # Kernel#warn is silent when warnings are off. Measured on ruby 3.4.8:
+      # `ruby -W0 -e 'warn "MSG"'` prints nothing, `ruby -W0 -e '$stderr.puts
+      # "MSG"'` prints MSG. Every command's rescue reports through here, so
+      # this is the one line that has to survive -W0; the cop's suggestion
+      # would take it away. It does not rescue the detail lines the commands
+      # emit with warn -- those already vanish under -W0.
+      # rubocop:disable Style/StderrPuts
+      $stderr.puts message
+      # rubocop:enable Style/StderrPuts
+    rescue Errno::EPIPE
+      # Same reason as verbose_output. A closed stderr must not turn a real
+      # failure into a different one, or mask the exit status the caller
+      # needs to see.
+      nil
+    end
+
+    # Keep the CommandFailed re-raise: ValidateCommand#run prints its own list
+    # of errors, so reporting it again here appends a second, redundant
+    # `Error: ...` line AFTER that list on every failed `elkrb validate`.
+    #
+    # Keep the Errno::EPIPE re-raise: a reader hanging up ends a SUCCESSFUL
+    # run (`elkrb layout big.json | head`), and Thor turns a re-raised EPIPE
+    # into exit 0. Wrap it instead and that clean pipeline starts exiting 1.
+    #
+    # The report is best-effort; see Elkrb::BestEffortWrite for why, and wrap
+    # any new non-result write -- a report, a progress line, anything that
+    # is not the write emitting the command's actual output -- the same way.
+    def fail_command(error, command)
+      hint = failure_hint(error, command)
+      raise error if error.is_a?(Errno::EPIPE)
+
+      if error.is_a?(CommandFailed)
+        BestEffortWrite.attempt { error_output hint }
+        raise error
+      end
+
+      message = error.message
+      BestEffortWrite.attempt do
+        error_output "Error: #{message}"
+        error_output hint
+      end
+      raise CommandFailed, message
+    end
+
+    def failure_hint(error, command)
+      return "Try: elkrb algorithms" if error.is_a?(AlgorithmNotFoundError)
+
+      "Try: elkrb help #{command}"
     end
   end
 end