rubydex 0.2.9 → 0.3.0

data/rust/rubydex/src/query/cypher/schema_info.rs

@@ -0,0 +1,161 @@
+//! Renders the Cypher property-graph model — node labels, relationship types, and node properties —
+//! for the `--schema` output. The model itself is defined once in [`super::schema`] (labels and
+//! properties as `NODE_LABELS`/`NODE_PROPERTIES`, relationships as [`RelType`]); this module only
+//! formats it, so there is a single source of truth.
+
+use cypher_parser::OutputFormat;
+use cypher_parser::value::write_json_string;
+
+use super::schema::{NODE_LABELS, NODE_PROPERTIES, RelType};
+
+/// Renders the schema catalog in the requested format.
+#[must_use]
+pub fn describe(format: OutputFormat) -> String {
+    match format {
+        OutputFormat::Table => render_table(),
+        OutputFormat::Json => render_json(),
+    }
+}
+
+fn render_table() -> String {
+    let mut out = String::new();
+
+    out.push_str("Node labels\n");
+    let label_rows: Vec<[&str; 3]> = NODE_LABELS
+        .iter()
+        .map(|l| [l.label, l.matches, l.description])
+        .collect();
+    push_table(&mut out, &["Label", "Matches", "Description"], &label_rows);
+
+    out.push_str("\nRelationship types\n");
+    let rel_rows: Vec<[&str; 4]> = RelType::all()
+        .map(|rel| {
+            let schema = rel.schema();
+            [schema.name, schema.from, schema.to, schema.description]
+        })
+        .collect();
+    push_table(&mut out, &["Type", "From", "To", "Description"], &rel_rows);
+
+    out.push_str("\nProperties\n");
+    let prop_rows: Vec<[&str; 3]> = NODE_PROPERTIES
+        .iter()
+        .map(|p| [p.node_type, p.property, p.description])
+        .collect();
+    push_table(&mut out, &["Node type", "Property", "Description"], &prop_rows);
+
+    out
+}
+
+/// Renders a single aligned table section. `N` is the column count.
+fn push_table<const N: usize>(out: &mut String, headers: &[&str; N], rows: &[[&str; N]]) {
+    let mut widths: [usize; N] = std::array::from_fn(|i| headers[i].chars().count());
+    for row in rows {
+        for (index, cell) in row.iter().enumerate() {
+            widths[index] = widths[index].max(cell.chars().count());
+        }
+    }
+
+    push_table_row(out, headers, &widths);
+    for (index, width) in widths.iter().enumerate() {
+        if index > 0 {
+            out.push_str("-+-");
+        }
+        for _ in 0..*width {
+            out.push('-');
+        }
+    }
+    out.push('\n');
+    for row in rows {
+        push_table_row(out, row, &widths);
+    }
+}
+
+fn push_table_row<const N: usize>(out: &mut String, cells: &[&str; N], widths: &[usize; N]) {
+    for (index, width) in widths.iter().enumerate() {
+        if index > 0 {
+            out.push_str(" | ");
+        }
+        let cell = cells[index];
+        out.push_str(cell);
+        for _ in 0..width.saturating_sub(cell.chars().count()) {
+            out.push(' ');
+        }
+    }
+    out.push('\n');
+}
+
+fn render_json() -> String {
+    let mut out = String::from("{\"node_labels\":[");
+    for (index, label) in NODE_LABELS.iter().enumerate() {
+        if index > 0 {
+            out.push(',');
+        }
+        out.push_str("{\"label\":");
+        write_json_string(&mut out, label.label);
+        out.push_str(",\"matches\":");
+        write_json_string(&mut out, label.matches);
+        out.push_str(",\"description\":");
+        write_json_string(&mut out, label.description);
+        out.push('}');
+    }
+
+    out.push_str("],\"relationships\":[");
+    for (index, rel) in RelType::all().enumerate() {
+        if index > 0 {
+            out.push(',');
+        }
+        let schema = rel.schema();
+        out.push_str("{\"type\":");
+        write_json_string(&mut out, schema.name);
+        out.push_str(",\"from\":");
+        write_json_string(&mut out, schema.from);
+        out.push_str(",\"to\":");
+        write_json_string(&mut out, schema.to);
+        out.push_str(",\"description\":");
+        write_json_string(&mut out, schema.description);
+        out.push('}');
+    }
+
+    out.push_str("],\"properties\":[");
+    for (index, prop) in NODE_PROPERTIES.iter().enumerate() {
+        if index > 0 {
+            out.push(',');
+        }
+        out.push_str("{\"node_type\":");
+        write_json_string(&mut out, prop.node_type);
+        out.push_str(",\"property\":");
+        write_json_string(&mut out, prop.property);
+        out.push_str(",\"description\":");
+        write_json_string(&mut out, prop.description);
+        out.push('}');
+    }
+
+    out.push_str("]}");
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn table_lists_labels_relationships_and_properties() {
+        let output = describe(OutputFormat::Table);
+        assert!(output.contains("Node labels"));
+        assert!(output.contains("Relationship types"));
+        assert!(output.contains("Properties"));
+        assert!(output.contains("Namespace"));
+        assert!(output.contains("HAS_PARENT"));
+        assert!(output.contains("unqualified_name"));
+    }
+
+    #[test]
+    fn json_is_well_formed_object() {
+        let output = describe(OutputFormat::Json);
+        assert!(output.starts_with("{\"node_labels\":["));
+        assert!(output.contains("\"relationships\":["));
+        assert!(output.contains("\"properties\":["));
+        assert!(output.contains("\"type\":\"DEFINES\""));
+        assert!(output.ends_with("]}"));
+    }
+}

data/rust/rubydex/src/query/cypher/tests.rs

@@ -0,0 +1,228 @@
+use super::run_query;
+use super::schema::RelType;
+use crate::model::graph::Graph;
+use crate::test_utils::GraphTest;
+use cypher_parser::{CypherValue, OutputFormat, ResultSet, execute, parse};
+
+#[test]
+fn relationship_metadata_is_self_consistent() {
+    // Guards the single source of truth: every relationship's catalog name must round-trip through
+    // `parse`, and every field must be populated.
+    for rel in RelType::all() {
+        let schema = rel.schema();
+        assert_eq!(RelType::parse(schema.name), Some(rel));
+        assert_eq!(RelType::parse(&schema.name.to_ascii_lowercase()), Some(rel));
+        assert!(!schema.from.is_empty(), "{} missing `from`", schema.name);
+        assert!(!schema.to.is_empty(), "{} missing `to`", schema.name);
+        assert!(!schema.description.is_empty(), "{} missing description", schema.name);
+    }
+}
+
+// Parser-only tests live in the `cypher-parser` crate. These exercise the executor and the
+// end-to-end query/format path against a real graph.
+
+fn fixture_graph() -> Graph {
+    let mut context = GraphTest::new();
+    context.index_uri(
+        "file:///zoo.rb",
+        "
+            module Walkable
+            end
+
+            class Animal
+              def speak; end
+            end
+
+            class Dog < Animal
+              include Walkable
+            end
+
+            class Cat < Animal
+            end
+        ",
+    );
+    context.resolve();
+    context.into_graph()
+}
+
+fn run(graph: &Graph, query: &str) -> ResultSet {
+    let parsed = parse(query).unwrap();
+    execute(graph, &parsed).unwrap()
+}
+
+fn column_strings(result: &ResultSet, column: usize) -> Vec<String> {
+    let mut values: Vec<String> = result.rows.iter().map(|row| row[column].to_display_string()).collect();
+    values.sort();
+    values
+}
+
+#[test]
+fn scans_declarations_by_label_and_property() {
+    let graph = fixture_graph();
+    let result = run(&graph, "MATCH (c:Class {name: 'Dog'}) RETURN c.name");
+    assert_eq!(result.columns, vec!["c.name".to_string()]);
+    assert_eq!(column_strings(&result, 0), vec!["Dog".to_string()]);
+}
+
+#[test]
+fn scans_label_disjunction() {
+    let graph = fixture_graph();
+    let result = run(
+        &graph,
+        "MATCH (n:Class|Module) WHERE n.name = 'Animal' OR n.name = 'Walkable' RETURN n.name, n.kind",
+    );
+    let names = column_strings(&result, 0);
+    assert_eq!(names, vec!["Animal".to_string(), "Walkable".to_string()]);
+}
+
+#[test]
+fn follows_inherits_relationship() {
+    let graph = fixture_graph();
+    let result = run(
+        &graph,
+        "MATCH (c:Class)-[:HAS_PARENT]->(p:Class) WHERE c.name = 'Dog' RETURN p.name",
+    );
+    assert_eq!(column_strings(&result, 0), vec!["Animal".to_string()]);
+}
+
+#[test]
+fn follows_incoming_relationship() {
+    let graph = fixture_graph();
+    let result = run(
+        &graph,
+        "MATCH (p:Class)<-[:HAS_PARENT]-(c:Class) WHERE p.name = 'Animal' RETURN c.name",
+    );
+    assert_eq!(column_strings(&result, 0), vec!["Cat".to_string(), "Dog".to_string()]);
+}
+
+#[test]
+fn follows_includes_relationship() {
+    let graph = fixture_graph();
+    let result = run(
+        &graph,
+        "MATCH (c:Class)-[:INCLUDES]->(m) WHERE c.name = 'Dog' RETURN m.name",
+    );
+    assert_eq!(column_strings(&result, 0), vec!["Walkable".to_string()]);
+}
+
+#[test]
+fn follows_owns_to_method() {
+    let graph = fixture_graph();
+    let result = run(
+        &graph,
+        "MATCH (c:Class)-[:OWNS]->(m:Method) WHERE c.name = 'Animal' RETURN m.unqualified_name",
+    );
+    assert!(column_strings(&result, 0).iter().any(|name| name.contains("speak")));
+}
+
+#[test]
+fn variable_length_ancestor_chain() {
+    let graph = fixture_graph();
+    let result = run(
+        &graph,
+        "MATCH (c:Class)-[:HAS_ANCESTOR]->(a) WHERE c.name = 'Dog' RETURN a.name",
+    );
+    let ancestors = column_strings(&result, 0);
+    assert!(ancestors.contains(&"Animal".to_string()));
+    assert!(ancestors.contains(&"Walkable".to_string()));
+    assert!(ancestors.contains(&"Object".to_string()));
+}
+
+#[test]
+fn traverses_document_to_declaration() {
+    let graph = fixture_graph();
+    let result = run(
+        &graph,
+        "MATCH (d:Document)-[:DEFINES]->(def:Definition)-[:DECLARES]->(decl) WHERE decl.name = 'Dog' RETURN decl.name",
+    );
+    assert_eq!(column_strings(&result, 0), vec!["Dog".to_string()]);
+}
+
+#[test]
+fn aggregation_counts_subclasses() {
+    let graph = fixture_graph();
+    let result = run(
+        &graph,
+        "MATCH (c:Class)-[:HAS_PARENT]->(p:Class) WHERE p.name = 'Animal' RETURN p.name, count(c) AS subclasses",
+    );
+    assert_eq!(result.rows.len(), 1);
+    assert_eq!(result.rows[0][0], CypherValue::Str("Animal".into()));
+    assert_eq!(result.rows[0][1], CypherValue::Int(2));
+}
+
+#[test]
+fn distinct_and_order_and_limit() {
+    let graph = fixture_graph();
+    let result = run(
+        &graph,
+        "MATCH (c:Class)-[:HAS_PARENT]->(p:Class) RETURN DISTINCT p.name ORDER BY p.name LIMIT 1",
+    );
+    assert_eq!(result.rows.len(), 1);
+    assert_eq!(result.rows[0][0], CypherValue::Str("Animal".into()));
+}
+
+#[test]
+fn where_with_boolean_operators() {
+    let graph = fixture_graph();
+    let result = run(
+        &graph,
+        "MATCH (c:Class) WHERE c.name = 'Dog' OR c.name = 'Cat' RETURN c.name",
+    );
+    assert_eq!(column_strings(&result, 0), vec!["Cat".to_string(), "Dog".to_string()]);
+}
+
+#[test]
+fn run_query_table_output() {
+    let graph = fixture_graph();
+    let output = run_query(
+        &graph,
+        "MATCH (c:Class {name: 'Dog'}) RETURN c.name",
+        OutputFormat::Table,
+    )
+    .unwrap();
+    assert!(output.contains("c.name"));
+    assert!(output.contains("Dog"));
+    assert!(output.contains("1 row"));
+}
+
+#[test]
+fn run_query_json_output() {
+    let graph = fixture_graph();
+    let output = run_query(
+        &graph,
+        "MATCH (c:Class {name: 'Dog'}) RETURN c.name",
+        OutputFormat::Json,
+    )
+    .unwrap();
+    assert_eq!(output, "[{\"c.name\":\"Dog\"}]");
+}
+
+#[test]
+fn unknown_relationship_type_errors() {
+    let graph = fixture_graph();
+    let parsed = parse("MATCH (a)-[:BOGUS]->(b) RETURN a").unwrap();
+    assert!(execute(&graph, &parsed).is_err());
+}
+
+#[test]
+fn document_uri_path_and_name_are_distinct() {
+    let graph = fixture_graph();
+    let result = run(
+        &graph,
+        "MATCH (d:Document) WHERE d.uri = 'file:///zoo.rb' RETURN d.uri, d.path, d.name",
+    );
+    assert_eq!(
+        result.columns,
+        vec!["d.uri".to_string(), "d.path".to_string(), "d.name".to_string()]
+    );
+    // `uri` is the full URI and `name` is the basename on every platform.
+    assert_eq!(column_strings(&result, 0), vec!["file:///zoo.rb".to_string()]);
+    assert_eq!(column_strings(&result, 2), vec!["zoo.rb".to_string()]);
+
+    // `path` is the decoded file-system path. A drive-less `file://` URI has no valid Windows path,
+    // so there it falls back to the raw URI; on Unix it decodes to `/zoo.rb`.
+    #[cfg(not(windows))]
+    assert_eq!(column_strings(&result, 1), vec!["/zoo.rb".to_string()]);
+    #[cfg(windows)]
+    assert_eq!(column_strings(&result, 1), vec!["file:///zoo.rb".to_string()]);
+}

data/rust/rubydex/src/query/cypher.rs

@@ -0,0 +1,57 @@
+//! A small Cypher query engine that runs read-only queries directly against the in-memory
+//! [`Graph`](crate::model::graph::Graph).
+//!
+//! Supported subset:
+//! - `MATCH` with node patterns `(v:Label {prop: value})` — labels may be a disjunction
+//!   (`(v:Class|Module)` matches a node with **any** of the listed labels) — and relationship
+//!   patterns `-[:TYPE]->`, `<-[:TYPE]-`, `-[:TYPE]-`, including variable-length `-[:TYPE*min..max]->`.
+//! - `WHERE` with `=`, `<>`, `<`, `<=`, `>`, `>=`, `CONTAINS`, `STARTS WITH`, `ENDS WITH`,
+//!   combined with `AND`, `OR`, `NOT`.
+//! - `RETURN` with `DISTINCT`, `AS` aliases, and the aggregates `count`, `collect`, `min`, `max`,
+//!   `sum`, `avg`.
+//! - `ORDER BY`, `SKIP`, `LIMIT`.
+//!
+//! See [`schema`] for the node labels and relationship types exposed to queries.
+
+// The whole Cypher engine — lexer, parser, AST, executor, values, and formatting — lives in the
+// graph-independent `cypher-parser` crate. rubydex only provides the `GraphProvider` mapping for its
+// `Graph` (in `schema`) and the static schema description (in `schema_info`).
+//
+// `Query` is the opaque parsed-query object: callers can `parse` a query string once (failing fast
+// on syntax errors), then `run_parsed` it against a graph that was built afterwards.
+pub use cypher_parser::{CypherError, OutputFormat, Query, parse};
+
+pub mod schema;
+pub mod schema_info;
+
+use crate::model::graph::Graph;
+
+/// Parses and executes a Cypher query against the graph, returning the formatted output.
+///
+/// # Errors
+///
+/// Returns a [`CypherError`] if the query cannot be parsed or executed.
+pub fn run_query(graph: &Graph, query: &str, output_format: OutputFormat) -> Result<String, CypherError> {
+    cypher_parser::run_query(graph, query, output_format)
+}
+
+/// Executes an already-parsed [`Query`] against the graph and formats the result. Pair with
+/// [`parse`] to validate a query before building the graph.
+///
+/// # Errors
+///
+/// Returns a [`CypherError`] if the query cannot be executed.
+pub fn run_parsed(graph: &Graph, query: &Query, output_format: OutputFormat) -> Result<String, CypherError> {
+    let result = cypher_parser::execute(graph, query)?;
+    Ok(cypher_parser::format::format(&result, output_format))
+}
+
+/// Returns a description of the queryable schema (node labels, relationship types, and properties)
+/// in the requested format. The schema is static and does not require a graph.
+#[must_use]
+pub fn schema(output_format: OutputFormat) -> String {
+    schema_info::describe(output_format)
+}
+
+#[cfg(test)]
+mod tests;

data/rust/rubydex/src/query.rs

@@ -15,6 +15,8 @@ use crate::model::keywords::{self, Keyword};
 use crate::model::name::NameRef;
 use crate::model::visibility::Visibility;
 
+pub mod cypher;
+
 /// Controls how declaration names are matched against the search query.
 #[derive(Default)]
 pub enum MatchMode {