Return Cypher query results as graph objects

[paracycle]

Goal

Build on the Cypher query engine from #868 so callers get matched graph nodes back as first-class objects, not as formatted text they have to re-parse or iterate over.

#868 added Rubydex::Query#render(graph, format), which runs a query and returns a table/json string — great for the CLI and humans, but a dead end for programmatic callers: to actually use a matched class or method you'd have to parse the formatted output, then look the node back up in the graph by name. This PR adds an object-returning sibling, Query#run(graph), that hands you the matched nodes directly.

What changes

• Rubydex::Query#render(graph, format = :table) — unchanged: rows → formatted String.
• Rubydex::Query#run(graph) — new: rows → Array<Hash> (T::Array[T::Hash[String, T::untyped]]), where the values are real Ruby objects:
  • a column that binds a node (e.g. RETURN c) comes back as a live Rubydex::Declaration / Definition / Document handle;
  • scalar columns (RETURN c.name, count(c)) come back as plain Ruby values (String, Integer, true/false, nil);
  • a map projection (RETURN c { .name, .kind }) comes back as a Ruby Hash, and a list comes back as a Ruby Array (elements decoded recursively).

So instead of:

# Before: query returns a string; you re-parse it, then re-find the node.
text = query.render(graph, :json)
JSON.parse(text).each do |row|
  decl = graph.find_declaration(row["c.name"])  # extra lookup just to get an object
  decl.definitions.each { ... }
end

you write:

# After: the matched node IS the object. No iteration to re-resolve it.
query = Rubydex::Query.parse("MATCH (c:Class)-[:HAS_PARENT]->(:Class {name: 'Animal'}) RETURN c")
query.run(graph).each do |row|
  decl = row["c"]            # => Rubydex::Declaration, already resolved
  decl.definitions           # navigate the graph directly
end

The query language does the matching and filtering; you get the resulting nodes back ready to use, without writing your own traversal/iteration to turn names back into graph objects.

How it works

• cypher-parser 0.8.1: the generic executor carries node identity and structured values. CypherValue covers Null/Bool/Int/Str scalars, Node { id, name, .. } for a bound graph node, and List / Map containers (so map projections like c { .name, .kind } survive execution). GraphProvider gains:

  • node_id(node) — encodes a node to an opaque id, so a bound node survives execution as an id rather than being flattened to text;
  • expand_in(node, rel_type) — walks a relationship backwards (incoming edges), enabling queries like (:Definition)<-[:DEFINES]-(:Document).

  The crate stays dependency-free and rubydex-agnostic.

• rubydex schema (query::cypher::schema): implements node_id and NodeRef::decode over the existing decl:/def:/doc:<u64> id scheme, and implements expand_in for the reversible relationships (DEFINES, DECLARES) so incoming traversals resolve to the right nodes.

• FFI (rubydex-sys): all Cypher-related code lives in a new cypher_api.rs module — CQueryResult, CParseResult, rdx_cypher_parse, rdx_cypher_query_free, rdx_cypher_schema, and the structured-result types. Only rdx_query_run (the formatted-string runner) remains in graph_api.rs. rdx_query_run_rows returns a CRunRows wrapping a CRowsIter opaque iterator (following the existing DeclarationsIter / DocumentsIter pattern), walked via rdx_rows_iter_{column_count,columns,len,next,free}. CCell is a tagged union (CCellTag: Null/Bool/Int/Str/Node/List/Map); Node cells carry a category (declaration/definition/document) plus the entity id, and Map stores parallel key/value arrays. A cstring_raw helper was added to utils.rs for allocating owned C strings across the FFI boundary.

• Gem (ext/rubydex/query.c, extending the file added in Query the in-memory graph with Cypher #868): Query#run walks the CRowsIter iterator into an Array<Hash>, decoding each cell — node cells into the appropriate Declaration / Definition / Document handle, lists into Array, maps into Hash, scalars into plain values. The iterator walk is wrapped in rb_ensure so rdx_rows_iter_free runs even if Ruby raises during cell conversion. Both render and run use a new rdxi_graph_from_object helper in graph.h to extract the graph pointer from the Graph VALUE.

Why this matters for both APIs

• Ruby API: queries become a graph-navigation tool, not just a reporting tool. Match with Cypher, then call methods on the returned handles — no manual name-based re-lookup, no iterating the whole graph to find what the query already found.
• Rust API: the executor now preserves node identity end-to-end (CypherValue::Node) and supports incoming-edge traversal (expand_in), so any GraphProvider-backed consumer — Rust callers, the FFI layer, future language servers/tools — can get matched nodes back by id and resolve them to their own representation, rather than being limited to formatted strings.

In short: the query does the matching; callers get the nodes, not a transcript of them.

Verification

• cargo build / cargo test green; clippy clean (-D warnings); cargo fmt --check clean.
• rake compile green; bundle exec ruby -Itest test/graph_test.rb → 110 runs, 0 failures (includes new object-result, map-projection, aggregation, reverse-traversal, and label-disjunction tests).

[vinistock]

Could we use rdxi_graph_from_handle here?

[paracycle]

rdxi_graph_from_handle is for handle objects (Declaration/Definition/Document) that store a back-reference to their parent Graph via HandleData.graph_obj. In Query#run, graph_obj is the Graph itself, not a handle, so it can't be used directly.

I added rdxi_graph_from_object in graph.h as the Graph-level equivalent, and used it in both render and run.