Rubydex

To ensure high performance and a good user experience when writing custom rules, follow these guidelines:

1. Minimize Diagnostics: One problem in the code should equal one diagnostic. Use related_information to provide context rather than emitting multiple separate errors for the same issue.
2. Optimize Graph Queries: Avoid looping through the entire graph (e.g., graph.declarations.select { ... }). Instead, use highly specific queries or the search API (e.g., graph["Foo"].descendants or graph.search("#method_name()")).
3. Avoid Disk I/O: Do not read files from disk within a rule. Rules should operate exclusively on the provided Rubydex::Graph to avoid performance hits and stale data issues.
4. Prefer Generic Rules: Instead of writing many highly specific rules, create generic, configurable rules (e.g., a RequiredParentClass rule instead of separate rules for models and controllers).

A resolved Rubydex::Graph can be shared across Ractors without copying. This is achieved through an RwLock on the Rust side rather than Ruby's freeze mechanism.

Important considerations:

• Mutation is allowed on frozen graphs: Methods like index_source, resolve, exclude_patterns, and encoding= work even if the graph has been made shareable. This allows for incremental updates (e.g., in an LSP) while worker Ractors are reading.
• Concurrency Responsibility: Because the underlying Rust allocation is shared, the caller is responsible for managing the order of concurrent writes and reads.
• No Cloning: You cannot use dup or clone on a graph; doing so will raise a RuntimeError to prevent memory issues or excessive memory usage.

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

The Rubydex graph is composed of three primary hierarchical abstractions:

• Document: Represents a file (whether committed to disk or not). Produced during Indexing.
• Definition: Represents a single source-level construct found at a specific location in the code (e.g., a specific class keyword usage in a file). It captures raw data without semantic meaning. Produced during Indexing.
• Declaration: Represents the global semantic concept of an entity. It combines all Definitions that contribute to the same fully qualified name. Produced during Resolution.

Relationship Hierarchy

Document (1) $\rightarrow$ many Definitions $\rightarrow$ one Declaration (per fully qualified name).

Graph Entry Points

• Bottom-up: Use a UriId (derived from a string URI) to find all declarations defined within a specific Document.
• Top-down: Use a DeclarationId (derived from a fully qualified name) to access data about a specific semantic entity directly.

┌─────────────┐
    | Declaration |  one per fully qualified name
    └─────────────┘
           ▲
           |   many definitions that contribute to the same fully qualified name -> one declaration
           ▼
    ┌─────────────┐
    | Definition  |   a single source-level construct
    └─────────────┘
           ▲
           |   one document -> the many definitions found inside it
           ▼
    ┌─────────────┐
    |  Document   | a file
    └─────────────┘

Rubydex operates in two primary phases to transform raw source code into a semantic graph:

1. Indexing: This phase traverses ASTs (from Ruby or RBS) to extract raw information exactly as found. It is document-specific and does not attempt to derive semantic meaning or cross-file relationships. Because Ruby's file loading order is unpredictable (due to autoload or runtime require), indexing alone cannot resolve constant references that depend on other files.

2. Resolution: This phase takes the indexed data and builds a semantic representation. It performs tasks such as:

   • Computing fully qualified names (e.g., Foo::Bar, Foo#method(), Bar#@ivar).
   • Resolving constant references to their target declarations.
   • Linearizing ancestor chains and tracking descendants.
   • Assigning semantic ownership (linking methods/constants to their classes).
   • Creating implicit singleton classes.

Resolution uses a worklist (unit queue) loop that iterates until it reaches a fixed-point (convergence), meaning no further progress can be made in resolving constants or ancestor chains.

A singleton class is a unique class created for a specific object to hold its singleton methods and instance variables.

Key Behaviors:

• Lazy Materialization: Singleton classes are usually created lazily when singleton-specific syntax (like def self.*, class << self, or extend) is used, or when obj.singleton_class is called.
• Receiver of Singleton Methods: The singleton class is the receiver for methods defined via def self.*, class << self, and modules mixed in via extend.
• Lexical Scope vs. Singleton Receiver: Inside a class << self block, self is the singleton class. However, lexical constant lookup still follows the surrounding constant scope. Constants defined inside a class << self block do not become part of the original class's namespace.
• Nested Singleton Classes: Using class << self inside another class << self block opens the singleton class of the current self (the singleton class of the singleton class).

Important Distinctions:

• Class Variables (@@var): These bypass singleton classes entirely and belong to the base class or module.
• Instance Variables (@var): When defined in the class body, these belong to the class's singleton class.
• Immutable Objects: Integers, floats, symbols, and frozen strings cannot have singleton classes; calling singleton_class on them raises a TypeError.

class Foo
  class << self # reopens (or creates) Foo's singleton class
    A = 1
    def bar; A; end
  end

  def self.baz; end # adds the method to Foo's singleton class

  @ivar = 1 # assigns a class instance variable on Foo's singleton class (NOT a class variable)
end