Prototype Cypher commands in the rdx console

Add `Rubydex::Console`, which backs `rdx console` with an IRB session that
keeps `graph` in scope (for Ruby, e.g. `graph["Foo"]`) and registers two
Cypher commands via IRB's modern command API:

  rubydex> query MATCH (n:Class|Module) RETURN n.name ORDER BY n.name
  rubydex> schema

The `query` command takes the rest of the line verbatim, so the Cypher
does not need to be valid Ruby or quoted. This is the clean, idiomatic
"query mode": rather than swapping the REPL's evaluator, Cypher lines are
prefixed with `query`.

- Extract the console out of exe/rdx into lib/rubydex/console.rb; the
  query-running logic lives in Console.run_query so it is testable without
  driving IRB.
- Treat IRB as a soft, runtime dependency rather than a gemspec one. IRB is
  a default gem, so it is not declared in the gemspec; the Cypher commands
  register only when the installed IRB exposes the command API (>= 1.13),
  and the console degrades to a plain Ruby session on older versions.

Author: paracycle

exe/rdx

@@ -108,11 +108,8 @@ when "console"
   graph = build_graph($stdout)
 
   begin
-    require "irb"
-    IRB.setup(nil)
-    IRB.conf[:IRB_NAME] = "rubydex"
-    workspace = IRB::WorkSpace.new(binding)
-    IRB::Irb.new(workspace).run(IRB.conf)
+    require "rubydex/console"
+    Rubydex::Console.start(graph)
   rescue LoadError
     abort("Interactive mode requires `irb` to be in the bundle")
   end

lib/rubydex/console.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "irb"
+
+module Rubydex
+  # Interactive console backing `rdx console`.
+  #
+  # On top of a normal IRB session (with `graph` in scope so you can call Ruby directly, e.g.
+  # `graph["Foo"]`), it registers commands that run Cypher against the same graph without needing
+  # valid Ruby syntax or quoting:
+  #
+  #   rubydex(main):001> query MATCH (n:Class|Module) RETURN n.name ORDER BY n.name
+  #   rubydex(main):002> schema
+  #
+  # The `query` command takes the rest of the line verbatim, so the Cypher does not have to parse as
+  # Ruby. This is the clean, idiomatic realization of a "query mode": instead of swapping the REPL's
+  # evaluator, Cypher lines are simply prefixed with `query`.
+  #
+  # The Cypher commands rely on IRB's command-registration API (IRB >= 1.13). On older IRB the
+  # console still works as a plain Ruby session; only the `query`/`schema` shortcuts are unavailable.
+  module Console
+    class << self
+      # The graph that the `query`/`schema` console commands operate on. Set by {.start}.
+      attr_accessor :graph
+
+      # Starts an interactive session. `graph` is exposed both as a local variable (for the Ruby
+      # side of the console) and to the Cypher commands via {.graph}.
+      def start(graph)
+        self.graph = graph
+
+        IRB.setup(nil)
+        IRB.conf[:IRB_NAME] = "rubydex"
+        IRB::Irb.new(IRB::WorkSpace.new(session_binding(graph))).run(IRB.conf)
+      end
+
+      # Runs a Cypher query against {.graph} and returns the formatted output, or a human-readable
+      # error message on failure. Extracted from the command so it can be exercised without IRB.
+      def run_query(cypher, format: :table)
+        cypher = cypher.to_s.strip
+        return "Usage: query <CYPHER>" if cypher.empty?
+
+        Rubydex::Query.parse(cypher).render(graph, format)
+      rescue ArgumentError => e
+        e.message
+      end
+
+      # Returns the queryable Cypher schema description.
+      def describe_schema(format: :table)
+        Rubydex::Query.schema(format)
+      end
+
+      private
+
+      # A binding that exposes `graph` as a local variable for the Ruby side of the console.
+      def session_binding(graph)
+        binding
+      end
+    end
+  end
+end
+
+# Register the Cypher commands only when the installed IRB exposes the command API (>= 1.13).
+# Otherwise stop loading here: the console still works as a plain Ruby session, just without the
+# `query`/`schema` shortcuts.
+begin
+  require "irb/command"
+  return unless defined?(IRB::Command::Base) && IRB::Command.respond_to?(:register)
+rescue LoadError
+  return
+end
+
+module Rubydex
+  module Console
+    # `query <CYPHER>` — runs a Cypher query against the console graph and prints the result.
+    class QueryCommand < IRB::Command::Base
+      category "Rubydex"
+      description "Run a Cypher query against the graph: query <CYPHER>"
+
+      def execute(arg)
+        puts(Console.run_query(arg))
+        nil
+      end
+    end
+
+    # `schema` — prints the queryable Cypher schema (labels, relationships, properties).
+    class SchemaCommand < IRB::Command::Base
+      category "Rubydex"
+      description "Describe the queryable Cypher schema"
+
+      def execute(_arg)
+        puts(Console.describe_schema)
+        nil
+      end
+    end
+  end
+end
+
+IRB::Command.register(:query, Rubydex::Console::QueryCommand)
+IRB::Command.register(:schema, Rubydex::Console::SchemaCommand)

test/console_test.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "helpers/context"
+require "json"
+require "rubydex/console"
+
+class ConsoleTest < Minitest::Test
+  include Test::Helpers::WithContext
+
+  def teardown
+    Rubydex::Console.graph = nil
+  end
+
+  def test_run_query_renders_table_against_the_console_graph
+    with_graph("class Animal; end\nclass Dog < Animal; end\n") do
+      output = Rubydex::Console.run_query("MATCH (c:Class)-[:INHERITS]->(p) WHERE c.name = 'Dog' RETURN p.name")
+
+      assert_match(/p\.name/, output)
+      assert_match(/Animal/, output)
+    end
+  end
+
+  def test_run_query_supports_json_format
+    with_graph("class Dog; end\n") do
+      output = Rubydex::Console.run_query("MATCH (c:Class {name: 'Dog'}) RETURN c.name", format: :json)
+
+      assert_equal("[{\"c.name\":\"Dog\"}]", output)
+    end
+  end
+
+  def test_run_query_returns_usage_for_blank_input
+    with_graph("class Dog; end\n") do
+      assert_equal("Usage: query <CYPHER>", Rubydex::Console.run_query("   "))
+    end
+  end
+
+  def test_run_query_returns_error_message_on_invalid_query
+    with_graph("class Dog; end\n") do
+      output = Rubydex::Console.run_query("MATCH (c RETURN c")
+
+      assert_match(/Cypher syntax error/, output)
+    end
+  end
+
+  def test_describe_schema_lists_relationships
+    output = Rubydex::Console.describe_schema(format: :json)
+    parsed = JSON.parse(output)
+
+    assert(parsed["relationships"].any? { |r| r["type"] == "INHERITS" })
+  end
+
+  def test_commands_are_registered_on_modern_irb
+    names = IRB::Command.commands.keys
+
+    assert_includes(names, :query)
+    assert_includes(names, :schema)
+  end
+
+  def test_query_runs_without_the_command_api
+    # The core query path must not depend on IRB's command registration, so the console still works
+    # (minus the `query`/`schema` shortcuts) on older IRB versions.
+    with_graph("class Dog; end\n") do
+      assert_equal("[{\"c.name\":\"Dog\"}]", Rubydex::Console.run_query("MATCH (c:Class {name: 'Dog'}) RETURN c.name", format: :json))
+    end
+  end
+
+  private
+
+  def with_graph(source)
+    with_context do |context|
+      context.write!("zoo.rb", source)
+      graph = Rubydex::Graph.new
+      graph.index_all(context.glob("**/*.rb"))
+      graph.resolve
+      Rubydex::Console.graph = graph
+      yield
+    end
+  end
+end