fusion-lang 0.0.1.alpha1 → 0.0.1

data/lib/fusion/cli/options.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+# === CLI internals ===
+#
+# Input: ARGV
+# Output: Options (use case, input/output modes, program, input)
+#
+# A misuse of the command line is a UsageError, reported as plain text on
+# stderr by exe/fusion, never a payloaded Fusion error. Most surface here while
+# parsing options; `-!` with empty stdin is the one caught later, while reading
+# input.
+
+require "optparse"
+
+module Fusion
+  module CLI
+    class Options
+      class UsageError < StandardError; end
+
+      USAGE = <<~TEXT
+        usage: fusion [options] <file.fsn>
+               fusion [options] -e '<source>'
+               fusion --repl
+
+        use cases (default: --repl with no arguments, otherwise --pipe):
+          -p, --pipe      apply the program to stdin; with no input, the
+                          program's own value is the result
+          -s, --stream    apply the program to each line of an NDJSON stream
+          -r, --repl      interactive expressions and `identifier = expression`
+
+        options:
+          -e, --execute '<source>'
+                          inline program instead of a file
+          -i, --input MODE
+                          how the input marks an error value
+          -o, --output MODE
+                          how the output marks an error value
+          -j, --jail DIR  confine @-references to DIR and its subtree
+                          (default: the program's directory; the stdlib is
+                          always reachable, stdin never contains @-references;
+                          use '*' to disable confinement)
+          -!              treat the input as an error value (unix input mode only)
+          -b, --skip-blank-lines
+                          drop blank input lines instead of echoing them (--stream only)
+
+        modes: unix, bang, array, object
+          unix    pipe only (default there): plain JSON; output: stdout/exit 0
+                  for values, stderr/exit 1 for error payloads
+          bang    a leading "!" marks an error value; cheapest encoding, but not
+                  valid JSON — prefer it only between Fusion programs
+          array   [0, value] marks a value, [1, payload] an error (default for --stream)
+          object  {"value": _} marks a value, {"error": _} an error
+      TEXT
+
+      MODES = %w[unix bang array object].freeze
+
+      attr_reader :use_case, :input_mode, :output_mode, :inline_source, :program_path, :jail
+
+      def initialize(use_case:, input_mode:, output_mode:, inline_source:, program_path:, error_input:, skip_blank_lines:, jail:)
+        @use_case = use_case
+        @input_mode = input_mode
+        @output_mode = output_mode
+        @inline_source = inline_source
+        @program_path = program_path
+        @error_input = error_input
+        @skip_blank_lines = skip_blank_lines
+        @jail = jail
+      end
+
+      def error_input?
+        @error_input
+      end
+
+      def skip_blank_lines?
+        @skip_blank_lines
+      end
+
+      def self.parse(argv)
+        pipe = false
+        stream = false
+        repl = false
+        input_modes = []
+        output_modes = []
+        error_input = false
+        skip_blank_lines = false
+        inline_source = nil
+        jail = nil
+
+        parser = OptionParser.new do |option|
+          option.on("-p", "--pipe") { pipe = true }
+          option.on("-s", "--stream") { stream = true }
+          option.on("-r", "--repl") { repl = true }
+          option.on("-i", "--input MODE") { |mode| input_modes << check_mode!(mode, "--input") }
+          option.on("-o", "--output MODE") { |mode| output_modes << check_mode!(mode, "--output") }
+          option.on("-e", "--execute SOURCE") { |source| inline_source = source }
+          option.on("-j", "--jail DIR") { |dir| jail = dir }
+          option.on("-!") { error_input = true }
+          option.on("-b", "--skip-blank-lines") { skip_blank_lines = true }
+        end
+        parser.require_exact = true # no abbreviations: "--s" is not a stand-in for "--stream"
+
+        # Whatever survives option parsing is positional: the program path.
+        positional = run_parser(parser, argv)
+
+        use_case = resolve_use_case(pipe: pipe, stream: stream, repl: repl, no_arguments: argv.empty?)
+        input_mode = resolve_mode(input_modes, "--input")
+        output_mode = resolve_mode(output_modes, "--output")
+
+        validate(use_case, input_mode, output_mode, error_input, skip_blank_lines, inline_source, jail, positional)
+      end
+
+      # Collapse the use-case flags into one use case; more than one is a misuse.
+      # With none: a bare `fusion` (no arguments) starts the REPL, while any other
+      # invocation is a pipe run.
+      def self.resolve_use_case(pipe:, stream:, repl:, no_arguments:)
+        selected = [(:pipe if pipe), (:stream if stream), (:repl if repl)].compact
+
+        case selected.length
+        when 0 then no_arguments ? :repl : :pipe
+        when 1 then selected.first
+        else raise UsageError, "choose one use case: --pipe, --stream, or --repl"
+        end
+      end
+
+      # The single mode for one direction, or nil if unset. Repeats of the same
+      # mode are fine; two different modes for the same flag are a misuse.
+      def self.resolve_mode(modes, flag)
+        distinct = modes.uniq
+
+        case distinct.length
+        when 0 then nil
+        when 1 then distinct.first
+        else raise UsageError, "conflicting #{flag} modes: #{distinct.join(', ')}"
+        end
+      end
+
+      # Run OptionParser, translating its parse errors into our UsageError so
+      # exe/fusion reports them as plain usage text (never a payloaded error).
+      def self.run_parser(parser, argv)
+        parser.parse(argv)
+      rescue OptionParser::InvalidOption => error
+        raise UsageError, "unknown option #{error.args.join(' ')}"
+      rescue OptionParser::MissingArgument => error
+        raise UsageError, missing_argument_message(error.args.first)
+      rescue OptionParser::ParseError => error
+        raise UsageError, error.message
+      end
+
+      # A MODE value -> its symbol, or a UsageError naming the valid modes.
+      def self.check_mode!(value, flag)
+        return value.to_sym if MODES.include?(value)
+
+        raise UsageError, "#{flag} expects one of: #{MODES.join(', ')} (got #{value})"
+      end
+
+      # Mirror the old per-flag wording when a value-taking option has no value.
+      # OptionParser reports whichever alias the user typed, so match both.
+      def self.missing_argument_message(flag)
+        case flag
+        when "-e", "--execute" then "-e/--execute requires a source argument"
+        when "-i", "--input" then "--input expects one of: #{MODES.join(', ')} (got nothing)"
+        when "-o", "--output" then "--output expects one of: #{MODES.join(', ')} (got nothing)"
+        when "-j", "--jail" then "-j/--jail requires a directory argument"
+        else "#{flag} requires an argument"
+        end
+      end
+
+      # Check the flag combination against the use case and fill in defaults.
+      def self.validate(use_case, input_mode, output_mode, error_input, skip_blank_lines, inline_source, jail, positional)
+        raise UsageError, "--skip-blank-lines is only for --stream" if skip_blank_lines && use_case != :stream
+
+        case use_case
+        when :repl
+          unless input_mode.nil? && output_mode.nil? && !error_input && inline_source.nil? && positional.empty?
+            raise UsageError, "--repl takes no program, no input, and no modes"
+          end
+          program_path = nil
+        when :stream
+          input_mode ||= :array
+          output_mode ||= :array
+          raise UsageError, "--stream does not support the unix mode" if input_mode == :unix || output_mode == :unix
+          raise UsageError, "-! requires the unix input mode" if error_input
+          program_path = inline_source ? nil : positional.shift
+          raise UsageError, "missing program (a .fsn file or -e)" unless inline_source || program_path
+          raise UsageError, "too many positional arguments" unless positional.empty?
+        when :pipe
+          input_mode ||= :unix
+          output_mode ||= :unix
+          raise UsageError, "-! requires the unix input mode" if error_input && input_mode != :unix
+          program_path = inline_source ? nil : positional.shift
+          raise UsageError, "missing program (a .fsn file or -e)" unless inline_source || program_path
+          raise UsageError, "too many positional arguments" unless positional.empty?
+        else
+          raise Unreachable, "Unknown use case #{use_case}"
+        end
+
+        new(
+          use_case: use_case,
+          input_mode: input_mode,
+          output_mode: output_mode,
+          inline_source: inline_source,
+          program_path: program_path,
+          error_input: error_input,
+          skip_blank_lines: skip_blank_lines,
+          jail: jail
+        )
+      end
+
+      private_class_method :validate, :resolve_use_case, :resolve_mode, :run_parser, :check_mode!, :missing_argument_message
+    end
+  end
+end

data/lib/fusion/cli/parser.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# === CLI internals ===
+
+require "json"
+
+module Fusion
+  module CLI
+    module Parser
+      extend self
+
+      # WirePair -> runtime value
+      def parse(wire_pair)
+        value = convert(JSON.parse(wire_pair.data))
+        wire_pair.status == 1 ? Interpreter::ErrorVal.new(value) : value
+      rescue JSON::ParserError
+        Interpreter::ErrorVal.from_runtime(
+          kind: "syntax_error",
+          origin: "input",
+          operation: "parsing JSON",
+          input: wire_pair.data,
+          message: "input is not valid JSON"
+        )
+      end
+
+      private
+
+      def convert(ruby_value)
+        case ruby_value
+        when nil then NULL
+        when Array then ruby_value.map { |item| convert(item) }
+        when Hash then ruby_value.transform_values { |value| convert(value) }
+        else ruby_value
+        end
+      end
+    end
+  end
+end

data/lib/fusion/cli/repl.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# === CLI internals ===
+
+require_relative "serializer"
+require_relative "encoder"
+require_relative "../interpreter/env"
+
+module Fusion
+  module CLI
+    class Repl
+      RESET      = "\e[0m"
+      LIGHT_BLUE = "\e[94m"
+      GREEN      = "\e[32m"
+      RED        = "\e[31m"
+
+      PROMPT              = "#{LIGHT_BLUE}fsn> #{RESET}"
+      CONTINUATION_PROMPT = "#{LIGHT_BLUE}...> #{RESET}"
+      VALUE_MARKER        = "#{GREEN}✔ #{RESET}"
+      ERROR_MARKER        = "#{RED}✗ #{RESET}"
+
+      # REPL entries report errors with the same site as inline (`-e`) code.
+      SITE = { origin: "code", file: "<inline>" }.freeze
+
+      def initialize(root_env:)
+        @root_env = root_env
+      end
+
+      def run
+        CLI.prepare!
+
+        require "reline"
+        Reline.output = $stderr
+        Reline.prompt_proc = proc do |lines|
+          lines.each_index.map { |i| i.zero? ? PROMPT : CONTINUATION_PROMPT }
+        end
+
+        # The session env is a child of the run's root, so it carries the jail;
+        # bindings accumulate here while loaded files stay isolated at the root.
+        environment = @root_env.child.set_context(:dir, Dir.pwd)
+
+        loop do
+          buffer = begin
+            Reline.readmultiline(PROMPT, true) { complete?(_1) }
+          rescue Interrupt
+            $stderr.puts("^C") # discard the half-typed entry and re-prompt
+            next
+          end
+
+          break if buffer.nil? # Ctrl-D on an empty line ends the session
+          next if buffer.strip.empty?
+
+          output = handle(buffer, environment)
+
+          marker = output.start_with?("!") ? ERROR_MARKER : VALUE_MARKER
+          $stderr.print(marker) # decoration on stderr
+          $stdout.puts(output)  # the clean value on stdout
+        end
+      end
+
+      # String -> yes/no
+      def complete?(buffer)
+        return true if buffer.strip.empty?
+
+        ast = Fusion::Parser.parse_repl(buffer, site: SITE)
+        ast.is_a?(AST::Expression) || ast.is_a?(AST::Statement::Assignment)
+      end
+
+      # String (+ Env) -> String
+      def handle(buffer, environment)
+        ast = Fusion::Parser.parse_repl(buffer, site: SITE)
+        runtime_value = CLI.evaluate(ast, environment)
+        wire_pair = Serializer.serialize(runtime_value, lenient: true)
+        Encoder.encode(wire_pair, mode: :bang)
+      end
+    end
+  end
+end

data/lib/fusion/cli/serializer.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# === CLI internals ===
+
+require_relative "../wire_pair"
+
+module Fusion
+  module CLI
+    module Serializer
+      extend self
+
+      # runtime value -> WirePair
+      # Only use "lenient: true" in the REPL!
+      def serialize(runtime_value, lenient: false)
+        message = catch(:unserializable) do
+          if runtime_value.is_a?(Interpreter::ErrorVal)
+            error = runtime_value
+            data = convert(error.payload, lenient: lenient || error.runtime?).to_json
+            return WirePair.new(status: 1, data: data)
+          else
+            return WirePair.new(status: 0, data: convert(runtime_value, lenient: lenient).to_json)
+          end
+        end
+
+        runtime_error = Interpreter::ErrorVal.from_runtime(
+          kind: "serialization_error",
+          origin: "output",
+          operation: "serializing result",
+          input: runtime_value,
+          message: message
+        )
+
+        serialize(runtime_error, lenient: true)
+      end
+
+      private
+
+      # Use "lenient: true" only for best-effort serialization of internal errors and the REPL.
+      def convert(runtime_value, lenient: false)
+        case runtime_value
+        when NULL
+          nil
+        when Float
+          return runtime_value if runtime_value.finite?
+          throw(:unserializable, "cannot serialize a non-finite number") unless lenient
+
+          "<#{runtime_value}>" # "<Infinity>" / "<-Infinity>" / "<NaN>"
+        when Array
+          runtime_value.map { |item| convert(item, lenient:) }
+        when Hash
+          runtime_value.transform_values { |value| convert(value, lenient:) }
+        when Interpreter::Func, Interpreter::NativeFunc
+          throw(:unserializable, "cannot serialize a function") unless lenient
+
+          "<function>"
+        when true, false, String, Numeric
+          runtime_value
+        when Interpreter::ErrorVal
+          if lenient
+            "!#{convert(runtime_value.payload, lenient:).to_json}"
+          else
+            raise Unreachable, "ErrorVal should have been handled at the top level of convert"
+          end
+        else
+          raise Unreachable, "Unhandled type in convert: #{runtime_value.class}"
+        end
+      end
+    end
+  end
+end

data/lib/fusion/cli.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+# === CLI tools ===
+#
+# Core data types:
+# - WirePair
+# - Fusion runtime value
+
+require_relative "wire_pair"
+require_relative "cli/options"
+
+require_relative "cli/decoder"
+require_relative "cli/parser"
+require_relative "interpreter"
+require_relative "cli/serializer"
+require_relative "cli/encoder"
+
+require_relative "cli/repl"
+
+module Fusion
+  module CLI
+    extend self
+
+    def prepare!
+      $stdout.sync = true
+      $stderr.sync = true
+      $stdin.set_encoding(Encoding::UTF_8)
+      $stdout.set_encoding(Encoding::UTF_8)
+      $stderr.set_encoding(Encoding::UTF_8)
+    end
+
+    def run(options)
+      case options.use_case
+      when :pipe
+        run_pipe(options)
+      when :stream
+        run_stream(options)
+      when :repl
+        run_repl(options)
+      else
+        raise Unreachable, "Unknown use case #{options.use_case}"
+      end
+    end
+
+    def run_pipe(options)
+      prepare!
+
+      root = root_environment(jail: jail_root(options))
+      program = load_program(options, root)
+
+      input = load_input(options)
+      output = if input.nil?
+        program
+      else
+        apply(parse(input), program, environment: root)
+      end
+
+      emit_output(serialize(output), output_mode: options.output_mode)
+    end
+
+    def run_stream(options)
+      prepare!
+
+      root = root_environment(jail: jail_root(options))
+      program = load_program(options, root)
+
+      $stdin.each_line do |line|
+        record = line.chomp
+
+        if record.strip.empty?
+          $stdout.puts unless options.skip_blank_lines?
+        else
+          input = decode(record, mode: options.input_mode)
+          output = apply(parse(input), program, environment: root)
+          $stdout.puts(encode(serialize(output), mode: options.output_mode))
+        end
+      end
+    end
+
+    def run_repl(options)
+      Repl.new(root_env: root_environment(jail: jail_root(options))).run
+    end
+
+    # String (treated as stdin) -> WirePair
+    # Doesn't support mode `:unix`
+    def decode(string, mode:)
+      Decoder.decode(string, mode:)
+    end
+
+    # WirePair -> runtime value
+    def parse(wire_pair)
+      Parser.parse(wire_pair)
+    end
+
+    # A binding-free root environment
+    def root_environment(jail: Dir.pwd)
+      Interpreter::Env.new.set_context(:jail, jail)
+    end
+
+    # String (treated as inline source) -> runtime value
+    def load_source(inline_source, root_env)
+      ast = Fusion::Parser.parse_file(inline_source, site: { origin: "code", file: "<inline>" })
+      return ast if ast.is_a?(Fusion::Interpreter::ErrorVal) # a parse error
+
+      inline_env = root_env.child.set_context(:dir, Dir.pwd)
+      Fusion::Interpreter.new(inline_env).evaluate_unit(ast)
+    end
+
+    # relative path -> runtime_value
+    def load_file(rel_path, root_env)
+      interp = Fusion::Interpreter.new(root_env)
+      abspath = File.expand_path(rel_path)
+      # The top-level program file is loaded by the runtime, not via an @-reference:
+      # the operation is "loading code", with the path as `input` (which file).
+      interp.load_file(abspath).force(operation: "loading code", input: interp.display_path(abspath), site: { origin: "code", file: nil })
+    end
+
+    # runtime value + runtime value -> runtime value
+    # input | function -> output
+    # Confines @-resolution to the environment's jail.
+    # Ignores the environment's bindings. The function carries its own closure.
+    def apply(input, function, environment:)
+      Interpreter.safe_apply(function, input, environment)
+    end
+
+    # expression (AST) -> runtime value
+    # Mutates environment if given an assignment statement.
+    # Confines @-resolution to the environment's jail.
+    # Has access to the environment's bindings.
+    def evaluate(ast, environment)
+      case ast
+      when AST::Statement::Assignment
+        value = Interpreter.safe_evaluate(ast.expression, environment)
+        environment.bind(ast.name, value, checked: false)
+        value
+      when AST::Expression
+        Interpreter.safe_evaluate(ast, environment)
+      else
+        raise Unreachable, "Unhandled AST node #{ast.class}"
+      end
+    end
+
+    # runtime value -> WirePair
+    # CAUTION: resolves "internal" error status, only use for final output
+    def serialize(runtime_value)
+      Serializer.serialize(runtime_value)
+    end
+
+    # WirePair -> String
+    # Doesn't support mode `:unix`
+    def encode(wire_pair, mode:)
+      Encoder.encode(wire_pair, mode:)
+    end
+
+    private
+
+    # stdin -> WirePair
+    def load_input(options)
+      text = $stdin.tty? ? "" : $stdin.read.strip
+
+      if text.empty?
+        # "-!" promises that stdin carries an error payload. CLI contract violation.
+        raise Options::UsageError, "-! requires input to mark as an error, but stdin was empty" if options.error_input?
+
+        nil
+      elsif options.input_mode == :unix
+        WirePair.new(status: options.error_input? ? 1 : 0, data: text)
+      else
+        decode(text, mode: options.input_mode)
+      end
+    end
+
+    # WirePair -> stdout/stderr
+    def emit_output(wire_pair, output_mode:)
+      if output_mode == :unix
+        channel = wire_pair.status.zero? ? $stdout : $stderr
+        channel.puts(wire_pair.data)
+        exit(wire_pair.status)
+      else
+        $stdout.puts(encode(wire_pair, mode: output_mode))
+        exit 0
+      end
+    end
+
+    # file/inline -> runtime value
+    def load_program(options, root_env)
+      if options.inline_source
+        load_source(options.inline_source, root_env)
+      else
+        load_file(options.program_path, root_env)
+      end
+    end
+
+    # The jail root for this run: the program's directory by default (cwd for
+    # inline `-e` and the REPL), or `--jail DIR` resolved against that base.
+    # `--jail '*'` opts out of confinement entirely (nil = unconfined).
+    def jail_root(options)
+      return nil if options.jail == "*"
+
+      base = options.program_path ? File.dirname(File.expand_path(options.program_path)) : Dir.pwd
+      root = options.jail ? File.expand_path(options.jail, base) : base
+      raise Options::UsageError, "jail directory not found: #{options.jail}" unless File.directory?(root)
+
+      root
+    end
+  end
+end