elkrb 1.0.0 → 2.0.0

data/lib/elkrb/command_resolver.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Elkrb
+  # Resolves a command name to the file the OS would attempt to execute for
+  # it, without running it. That is strictly weaker than "it will run": a
+  # script whose interpreter is missing is a regular file, is executable, and
+  # still fails to exec. What this establishes is WHICH file the name reaches.
+  # Ruby execs a metacharacter-free command string itself and searches PATH
+  # for it, so a name with a separator is used as written and a bare name is
+  # looked up along PATH. Asking that question is a job of its own, separate
+  # from running the command, and it carries no instance state -- the answer
+  # depends on PATH, the filesystem and the working directory, none of which
+  # this unit owns.
+  module CommandResolver
+    module_function
+
+    # The first candidate that resolves, or nil.
+    def resolve(candidates)
+      candidates.find { |path| runnable?(path) }
+    end
+
+    # The absolute file a bare name resolves to via PATH, or the matched
+    # candidate for a name that already carries a separator -- nil when
+    # `runnable?` is false.
+    #
+    # Return the candidate that MATCHED, never `path` or
+    # `File.join(dir, path)`. On Windows `executable_candidates` fans an
+    # extensionless name out to its PATHEXT forms ("dot" -> "dot.exe"), so
+    # `path` is the form guaranteed NOT to exist and `File.realpath` would
+    # resolve it against the working directory instead of the PATH entry
+    # that matched.
+    def resolved_path(path)
+      return matched_candidate(path) if separator_form?(path)
+
+      dir = path_directories.find { |each| resolves_in_directory?(each, path) }
+      dir && matched_candidate(path, dir)
+    end
+
+    # Re-finds the candidate `runnable?` already confirmed, because neither
+    # it nor `resolves_in_directory?` keeps a reference to it.
+    def matched_candidate(path, dir = nil)
+      found = executable_candidates(path).find do |each|
+        executable_file?(dir ? File.join(dir, each) : each)
+      end
+      found && (dir ? File.join(dir, found) : found)
+    end
+
+    # `File.executable?` on a bare name answers about the WORKING DIRECTORY
+    # rather than about PATH, which is why it is not asked here.
+    #
+    # On Windows, CreateProcess (what `system`/backtick ultimately calls) does
+    # not require an exact filename match: given "dot" it also tries "dot"
+    # suffixed with each extension in PATHEXT, in order, both for a bare name
+    # walked along PATH and for a name given with a separator. POSIX exec has
+    # no such behaviour, so `executable_candidates` is a no-op there.
+    def runnable?(path)
+      if separator_form?(path)
+        executable_candidates(path).any? do |candidate|
+          executable_file?(candidate)
+        end
+      else
+        path_directories.any? { |dir| resolves_in_directory?(dir, path) }
+      end
+    end
+
+    def separator_form?(path)
+      return true if path.include?(File::SEPARATOR)
+
+      windows? && File::ALT_SEPARATOR && path.include?(File::ALT_SEPARATOR)
+    end
+
+    def resolves_in_directory?(dir, path)
+      executable_candidates(path).any? do |candidate|
+        executable_file?(File.join(dir, candidate))
+      end
+    end
+
+    # `File.executable?` alone is true for a DIRECTORY, because directories
+    # are searchable, and exec is not. `File.file?` alone is true for a data
+    # file. Both conjuncts are load-bearing.
+    def executable_file?(path)
+      File.file?(path) && File.executable?(path)
+    end
+
+    # A path that already carries a PATHEXT-listed extension (e.g. "dot.exe")
+    # is used as written -- only an EXTENSION-LESS name gets the PATHEXT
+    # fan-out, matching what CreateProcess actually does.
+    def executable_candidates(path)
+      return [path] unless windows?
+      return [path] if pathext.include?(File.extname(path).upcase)
+
+      pathext_candidates(path)
+    end
+
+    # The Windows filesystem is case-insensitive, so CreateProcess matches
+    # "dot.exe" whether PATHEXT names it ".EXE" or ".exe". Trying both cases
+    # here matches that on a case-SENSITIVE filesystem too (Linux/macOS CI
+    # running this logic under a Windows stub), rather than depending on the
+    # host filesystem's case sensitivity to agree.
+    def pathext_candidates(path)
+      pathext.flat_map do |extension|
+        ["#{path}#{extension}", "#{path}#{extension.downcase}"]
+      end.uniq
+    end
+
+    # PATHEXT is always ";"-delimited on Windows, independent of
+    # `File::PATH_SEPARATOR` -- which on a non-Windows host running under a
+    # stubbed `windows?` (as the specs do, to test this logic on any CI
+    # platform) is ":" and would silently produce one useless candidate.
+    # An entry missing its leading dot (a malformed but observed PATHEXT,
+    # e.g. "EXE" instead of ".EXE") is normalised here rather than left to
+    # silently never match `File.extname`, which always includes the dot.
+    def pathext
+      raw = ENV.fetch("PATHEXT", ".COM;.EXE;.BAT;.CMD").split(";")
+      raw.map(&:strip).reject(&:empty?)
+        .map { |ext| ext.start_with?(".") ? ext : ".#{ext}" }
+    end
+
+    def windows?
+      Gem.win_platform?
+    end
+
+    # Keep the `.b` and `split(..., -1)`: a raw (non-UTF-8) PATH byte must not
+    # raise, and a trailing/empty field must not be dropped -- both silently
+    # break resolution for a later, valid PATH entry otherwise. This is a
+    # documented CONTAINMENT, not full parity with exec: an unset PATH here
+    # is treated as empty, while exec also searches libruby's compiled-in
+    # default list (see gate record for the measured value) -- so this can
+    # under-report but never over-report a directory exec would search.
+    def path_directories
+      fields = ENV.fetch("PATH", "").b.split(File::PATH_SEPARATOR, -1)
+      fields = [""] if fields.empty?
+      fields.map { |field| field.empty? ? "." : expand_tilde(field) }
+    end
+
+    # Expand only a bare `~` or `~/...` PATH entry against `$HOME`, matching
+    # what the shell does before `render`'s `system(cmd)` ever sees PATH.
+    # Leave `~user` (a third party's home directory) un-expanded rather than
+    # querying the OS user database -- it still cannot false-positive-match
+    # via `executable_file?`, only under-report, same as `path_directories`.
+    def expand_tilde(field)
+      return field unless field.start_with?("~")
+
+      tilde_expansion(field) || field
+    end
+
+    # Split from `expand_tilde` so each holds one job: this one turns a
+    # confirmed `~` PATH entry into its expansion or nothing, and never
+    # touches a field that is not one.
+    def tilde_expansion(field)
+      rest = tilde_rest(field)
+      return unless rest
+
+      home = home_directory
+      return if home.to_s.empty?
+
+      "#{home.b}#{rest}"
+    end
+
+    # `Dir.home` (not `ENV["HOME"]` directly) so this agrees with what the
+    # shell itself consults for `~` expansion; it raises when no home
+    # directory can be determined at all, rather than returning nil, so
+    # that is the one case caught here. The rescue body is empty on
+    # purpose -- it already evaluates to `nil`, so an explicit `nil` line
+    # would be a no-op.
+    def home_directory
+      Dir.home
+    rescue ArgumentError
+      # empty on purpose -- already evaluates to nil
+    end
+
+    # `nil` means "not a `~` or `~/...` PATH entry" -- distinct from `""`,
+    # which is the valid rest of a bare `~`. `field[1..]` is never nil here:
+    # `field` always has at least one byte (the leading `~`), so index 1 is
+    # at worst equal to its length, which slices to `""` rather than failing.
+    def tilde_rest(field)
+      rest = field[1..]
+      rest if rest.empty? || rest.start_with?(File::SEPARATOR)
+    end
+  end
+end
+
+# Internal. Kept off the public surface deliberately; `private_constant` sits
+# out here because inside the namespace it makes `Elkrb` a non-namespacing
+# module, which reek then requires a descriptive comment for.
+Elkrb.private_constant :CommandResolver

data/lib/elkrb/commands/batch_command.rb

@@ -2,6 +2,8 @@
 
 require "fileutils"
 
+require_relative "../best_effort_write"
+
 module Elkrb
   module Commands
     # Command for processing multiple graph files in batch
@@ -23,7 +25,13 @@ module Elkrb
         files = Dir.glob(pattern, File::FNM_EXTGLOB)
 
         if files.empty?
-          puts "No graph files found in #{@directory}"
+          # Best-effort: this notice carries no result -- there is nothing
+          # left to do either way, so a dead stdout must not decide the
+          # exit status here any more than it does after real work below.
+          # See Elkrb::BestEffortWrite.
+          BestEffortWrite.attempt do
+            puts "No graph files found in #{@directory}"
+          end
           return
         end
 
@@ -42,14 +50,29 @@ module Elkrb
           warn "⚠ Error processing #{file}: #{e.message}"
         end
 
-        # Summary
-        puts ""
-        puts "✓ Processed #{success_count} file(s) → #{@options[:output_dir]}"
-        puts "⚠ #{error_count} error(s)" if error_count.positive?
+        # Best-effort: every file above is already written to output_dir.
+        # This summary must not decide the exit status -- see
+        # Elkrb::BestEffortWrite. fail_on_errors decides it instead.
+        BestEffortWrite.attempt do
+          puts ""
+          puts "✓ Processed #{success_count} file(s) → #{@options[:output_dir]}"
+          puts "⚠ #{error_count} error(s)" if error_count.positive?
+        end
+
+        fail_on_errors(error_count, files.size)
       end
 
       private
 
+      # The summary alone would let a batch that failed on every file still
+      # exit 0, so a non-empty error count has to reach the caller.
+      def fail_on_errors(error_count, total)
+        return unless error_count.positive?
+
+        require_relative "../errors"
+        raise Elkrb::Error, "#{error_count} of #{total} file(s) failed"
+      end
+
       def process_file(file)
         basename = File.basename(file, File.extname(file))
         output_file = File.join(@options[:output_dir],

data/lib/elkrb/commands/convert_command.rb

@@ -2,7 +2,9 @@
 
 require "json"
 require "yaml"
-require "fileutils"
+
+require_relative "../atomic_destination"
+require_relative "../best_effort_write"
 
 module Elkrb
   module Commands
@@ -17,6 +19,7 @@ module Elkrb
       def run
         # Load source file
         graph = load_any_format(@file)
+        graph = graph_from_hash(graph) if graph.is_a?(Hash)
 
         # Detect target format
         target_format = detect_format(@options[:output])
@@ -24,63 +27,28 @@ module Elkrb
         # Convert
         content = export_to_format(graph, target_format)
 
-        # Write output
+        # Write output -- this is the result. Everything after it is best-effort.
         write_output(content, @options[:output])
 
-        puts "✓ Converted #{@file} → #{@options[:output]} (#{target_format})"
+        report_success(target_format)
       end
 
       private
 
-      def load_any_format(file)
-        raise ArgumentError, "File not found: #{file}" unless File.exist?(file)
-
-        content = File.read(file)
-        ext = File.extname(file).downcase
-
-        case ext
-        when ".json"
-          require_relative "../graph/graph"
-          Elkrb::Graph::Graph.from_json(content)
-        when ".yml", ".yaml"
-          require_relative "../graph/graph"
-          Elkrb::Graph::Graph.from_yaml(content)
-        when ".elkt"
-          require_relative "../parsers/elkt_parser"
-          Elkrb::Parsers::ElktParser.parse(content)
-        when ".dot", ".gv"
-          raise ArgumentError,
-                "DOT format input not yet supported. Use JSON, YAML, or ELKT."
-        else
-          detect_and_parse(content)
+      # Best-effort: the file written above is already the result. This
+      # confirmation must not decide the exit status -- see
+      # Elkrb::BestEffortWrite.
+      def report_success(target_format)
+        BestEffortWrite.attempt do
+          puts "✓ Converted #{@file} → #{@options[:output]} (#{target_format})"
         end
       end
 
-      def detect_and_parse(content)
-        require_relative "../graph/graph"
-
-        # Try JSON first
-        begin
-          return Elkrb::Graph::Graph.from_json(content)
-        rescue JSON::ParserError
-          # Not JSON
-        end
-
-        # Try YAML
-        begin
-          return Elkrb::Graph::Graph.from_yaml(content)
-        rescue Psych::SyntaxError
-          # Not YAML
-        end
+      def load_any_format(file)
+        raise ArgumentError, "File not found: #{file}" unless File.exist?(file)
 
-        # Try ELKT
-        begin
-          require_relative "../parsers/elkt_parser"
-          Elkrb::Parsers::ElktParser.parse(content)
-        rescue StandardError
-          raise ArgumentError,
-                "Unable to parse input file. Supported formats: JSON, YAML, ELKT"
-        end
+        require_relative "../format_sniffer"
+        Elkrb::FormatSniffer.read(File.read(file), File.extname(file).downcase)
       end
 
       def detect_format(filename)
@@ -102,6 +70,11 @@ module Elkrb
         end
       end
 
+      def graph_from_hash(hash)
+        require_relative "../graph/graph"
+        Elkrb::Graph::Graph.from_hash(hash)
+      end
+
       def export_to_format(graph, format)
         case format
         when :json
@@ -120,10 +93,7 @@ module Elkrb
       end
 
       def write_output(content, filename)
-        dir = File.dirname(filename)
-        FileUtils.mkdir_p(dir)
-
-        File.write(filename, content)
+        AtomicDestination.write(filename, content)
       end
     end
   end