rubydex 0.2.8 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b27fe66d59bdafd3b040278baaca0607a87861d132d70cc7ad65f9edb75c049
-  data.tar.gz: 1036e909678edd8183e1359ba9b45323d1e7a26ad99847d3382583a3f97d1f61
+  metadata.gz: cf823835a70dee735f2dc0e898eb1d47be47e4ab635a6be4de5677ceaf6bbe53
+  data.tar.gz: 663389c429d729bf8d9191f54b7eafe92b8ecb8e0c0a32e5b3f6adba3365f3fa
 SHA512:
-  metadata.gz: 884a896d38505cdb97ddc2a83b96364dc918f7f449349bf37e0d54675d630750300856df10dc6ab13e80b20d03979cbef5122ca2cc7ed20a160e64cf8ec421bd
-  data.tar.gz: cfd66ff47db6ac89e6f5514d307e48dcb5f252c5132eeb17328cf067365c1d764b6f9f87609483135815bf5760502992a9de107322e9445b2a99deacc9dcf7a5
+  metadata.gz: aa17ed0f03e392c4ad1a2bf256d3472057d7a78a2baca596bb72f80c06d1fe36d7fa80878ddfabe740ca0b8d23f961d01afe9ab0211219e2f41b36b4587b819d
+  data.tar.gz: 86d70527d4bcee2b8e90bbebb33912e1f5a6bf1f7fe9ce6e1435e7fff918829ae2a8de692072ab34fca42a199f5cfce5a12e18f77b6f08d5b8ca274c3e8f83f4

data/README.md

@@ -3,6 +3,8 @@
 This project is a high-performance static analysis toolkit for the Ruby language. The goal is to be a solid
 foundation to power a variety of tools, such as type checkers, linters, language servers and more.
 
+[Ruby API Documentation](https://shopify.github.io/rubydex/)
+
 ## Usage
 
 Both Ruby and Rust APIs are made available through a gem and a crate, respectively. Here's a simple example
@@ -77,6 +79,70 @@ diagnostic.message
 diagnostic.location
 ```
 
+## Ractor Safety
+
+A resolved `Rubydex::Graph` can be shared across Ractors without copying:
+
+```ruby
+graph = Rubydex::Graph.new
+graph.index_workspace
+graph.resolve
+Ractor.make_shareable(graph)
+
+# Worker Ractors can now read the graph in parallel
+ractor = Ractor.new(graph) { |g| g["Foo"]&.name }
+ractor.value
+```
+
+Thread safety comes from an `RwLock` on the Rust side, **not** from Ruby's
+`freeze`. This is a deliberate, but potentially surprising, choice:
+
+- A frozen (or `make_shareable`'d) graph **can still be mutated** — methods like
+  `index_source`, `resolve`, `exclude_patterns`, and `encoding=` work on a frozen
+  graph. This supports interactive use cases (LSP/MCP) that need incremental
+  edits while worker Ractors read concurrently.
+- Because the same underlying allocation is shared, callers are responsible for
+  ordering concurrent writes and reads, as with any shared mutable state across
+  Ractors.
+- Graphs cannot be `dup`'d or `clone`'d; both raise `RuntimeError` to avoid
+  aliasing the Rust allocation (which would double-free on GC) or ballooning
+  memory with a deep copy.
+
+## Querying with Cypher
+
+Rubydex exposes the indexed graph through a read-only subset of the
+[Cypher](https://opencypher.org/) query language. Only read clauses (`MATCH`,
+`WHERE`, `RETURN`, ...) are supported; there is no way to mutate the graph.
+
+From the command line:
+
+```bash
+# Run a query against the current workspace
+bundle exec rdx query "MATCH (c:Class)-[:DEFINES]->(m:Method) RETURN c.name, m.name"
+
+# Render results as JSON instead of a table
+bundle exec rdx query "MATCH (c:Class) RETURN c.name" --format json
+
+# Describe the queryable schema (node labels and relationship types) without indexing
+bundle exec rdx query --schema
+```
+
+From Ruby:
+
+```ruby
+graph = Rubydex::Graph.new
+graph.index_workspace
+graph.resolve
+
+# Parse once, render against a graph as a table or JSON string
+query = Rubydex::Query.parse("MATCH (c:Class) RETURN c.name")
+puts query.render(graph, "table")
+puts query.render(graph, "json")
+
+# Describe the schema
+puts Rubydex::Query.schema("table")
+```
+
 ## MCP Server (Experimental)
 
 Rubydex can run as an MCP (Model Context Protocol) server, enabling AI assistants
@@ -94,16 +160,16 @@ like Claude to semantically query your Ruby codebase.
    bundle install
    ```
 
-3. Configure your MCP client to run `bundle exec rubydex_mcp`.
+3. Configure your MCP client to run `bundle exec rdx mcp`.
 
    Using Claude Code as an example:
    ```bash
-   claude mcp add --scope project rubydex -- bundle exec rubydex_mcp
+   claude mcp add --scope project rubydex -- bundle exec rdx mcp
    ```
 
    Using Codex as an example:
    ```bash
-   codex mcp add rubydex -- bundle exec rubydex_mcp
+   codex mcp add rubydex -- bundle exec rdx mcp
    ```
 
    Start your MCP client from that project directory. The MCP server indexes