WIP

Author: st0012

docs/plans/2026-01-21-dsl-definitions-design.md

@@ -23,12 +23,13 @@ Capture DSL method calls as `DslDefinition` during indexing, then process them a
 
 ### Phase 1: Indexing
 
-The `Graph` maintains an allowlist of DSL target method names:
+The `Graph` maintains a registry of DSL processors. During indexing, the method `is_dsl_target()` checks if a method name matches any registered processor:
 
 ```rust
-// In Graph
-internal_dsl_targets: Vec<StringId>,  // e.g., ["new", "attr_accessor"]
-// Future: external_dsl_targets for plugins
+// In Graph - DSL targets are derived from registered processors
+pub fn is_dsl_target(&self, method_name: &StringId) -> bool {
+    self.dsl_processors.iter().any(|p| p.method_name == *method_name)
+}
 ```
 
 **Two definition types are created during indexing:**
@@ -83,24 +84,37 @@ Standard resolution runs, which resolves `receiver_name` to a fully qualified na
 
 ### Phase 3: DSL Processing
 
-A new method `process_dsl_definitions()` is called after `resolve_all()`. It processes all `ConstantToDslDefinition`s:
+A new method `process_dsl_definitions()` is called after `resolve_all()`. It iterates over all `DslDefinition`s (not just those with constant assignments):
 
-1. Look up the referenced `DslDefinition`
-2. Get the resolved receiver via `graph.names().get(&receiver_name)`
-3. Dispatch to handler based on resolved receiver + method name:
+1. Get the `DslDefinition`
+2. Resolve the receiver to a `DeclarationId` (if any)
+3. Look up any associated `ConstantToDslDefinition` (optional)
+4. Find a matching processor from the registry and dispatch
 
-```text
-resolved receiver = ::Class, method = "new"  → ClassNewHandler
-resolved receiver = ::Module, method = "new" → ModuleNewHandler
-// Future: ::Struct, plugin-registered handlers
+```rust
+fn process_single_dsl_definition(&mut self, dsl_def_id: DefinitionId) {
+    let dsl_def = /* get DslDefinition */;
+    let receiver_decl_id = /* resolve receiver */;
+    let method_name = /* get method name string */;
+    let const_to_dsl = self.find_const_to_dsl_for(dsl_def_id);
+
+    if let Some(processor) = self.graph.dsl_processors()
+        .iter()
+        .find(|p| (p.matches)(receiver_decl_id, &method_name))
+    {
+        (processor.handle)(self.graph, &dsl_def, const_to_dsl.as_ref());
+    }
+    // No handler → DSL stays as-is
+}
 ```
 
-**Handler outcomes:**
+**Handler responsibilities:**
 
-- **Handler matches (e.g., `::Class.new`)**: Transform `ConstantToDslDefinition` into `DynamicClassDefinition` with the constant name. Creates `ClassDeclaration`.
-- **No handler matches (e.g., `SomeClass.new`)**: Transform `ConstantToDslDefinition` into regular `ConstantDefinition`. We don't know what `SomeClass.new` returns.
+- **Create appropriate definitions** (e.g., `DynamicClassDefinition` for `Class.new`)
+- **Handle fallback cases internally** (e.g., create `ConstantDefinition` if processing can't complete)
+- **Reassign owned members** to the new definition by updating their `lexical_nesting_id`
 
-Each handler also decides what to do with owned members (reassign to the new definition, discard, etc.). When members are reassigned, their `lexical_nesting_id` is NOT updated - it preserves the lexical structure as written in source code.
+Each handler decides what to do with owned members (reassign to the new definition, discard, etc.). When members are reassigned, their `lexical_nesting_id` IS updated to point to the new `DynamicClassDefinition` or `DynamicModuleDefinition`. This ensures that `resolve_lexical_owner` can find the correct declaration during Phase 4 resolution.
 
 ### Phase 4: Incremental Resolution
 
@@ -118,25 +132,38 @@ resolver.resolve_all();           // Phase 4
 
 ### Argument Representation
 
-Arguments are captured in a structured format to save downstream consumers from parsing:
+Arguments are captured as raw source text strings. This keeps indexing simple - resolution handlers interpret the strings as needed:
 
 ```rust
-enum DslArgument {
-    Symbol(StringId),
-    String(StringId),
-    Boolean(bool),
-    Integer(i64),
-    Constant(NameId),
-    Block { offset: Offset },  // Location for AST revisit if needed
+/// Represents a single argument in a DSL call.
+/// Values are captured as raw source text strings.
+pub enum DslArgument {
+    /// A positional argument (e.g., `Parent` in `Class.new(Parent)`)
+    Positional(String),
+    /// A keyword argument (e.g., `class_name: "User"`)
+    KeywordArg { key: String, value: String },
+    /// A splat argument (e.g., `*args`)
+    Splat(String),
+    /// A double splat argument (e.g., `**kwargs`)
+    DoubleSplat(String),
+    /// A block argument (e.g., `&block`)
+    BlockArg(String),
 }
 
 struct DslArgumentList {
-    positional: Vec<DslArgument>,
-    keyword: HashMap<StringId, DslArgument>,
-    block: Option<Offset>,
+    arguments: Vec<DslArgument>,
+    block_offset: Option<Offset>,  // Location of do...end block
 }
 ```
 
+Example: `Foo.new("123", bar: true, *args, **kwargs, &block)` becomes:
+
+- `Positional("\"123\"")`
+- `KeywordArg { key: "bar", value: "true" }`
+- `Splat("args")`
+- `DoubleSplat("kwargs")`
+- `BlockArg("block")`
+
 ### Block Ownership
 
 All DSL calls automatically own their block contents. This simplifies indexing logic - the handler decides what to do with owned definitions during processing:
@@ -199,8 +226,8 @@ end
 - `DslDefinition(receiver: SomeClass, method: "new")`
 - `ConstantToDslDefinition(constant: Foo, dsl: DslDefinition)`
 - After resolution, `SomeClass` resolves to `::SomeClass` (not `::Class`)
-- No handler matches
-- `ConstantToDslDefinition` becomes regular `ConstantDefinition(Foo)`
+- No processor matches (neither `class_new_matches` nor `module_new_matches` return true)
+- DSL stays as-is (no transformation happens)
 
 ## Example: RSpec (Future Plugin)
 
@@ -284,19 +311,92 @@ No new declaration types needed. Dynamic definitions create standard declaration
 - `DynamicClassDefinition` → `ClassDeclaration`
 - `DynamicModuleDefinition` → `ModuleDeclaration`
 
-### DSL Handler Trait
+### DSL Processor Registry
+
+DSL processors are registered with the Graph using function pointers (not trait objects) for simplicity:
 
 ```rust
-trait DslHandler {
-    /// Returns true if this handler should process the given DSL call
-    fn handles(&self, resolved_receiver: &str, method_name: &str) -> bool;
+/// A DSL processor that can match and handle specific DSL patterns.
+/// Lives in model/dsl_processors.rs
+pub struct DslProcessor {
+    /// The method name this processor is interested in (e.g., "new")
+    pub method_name: StringId,
+    /// Returns true if this processor handles the given receiver/method combination
+    pub matches: fn(receiver_decl_id: Option<DeclarationId>, method_name: &str) -> bool,
+    /// Processes the DSL and mutates the graph accordingly
+    pub handle: fn(
+        graph: &mut Graph,
+        dsl_def: &DslDefinition,
+        const_to_dsl: Option<&ConstantToDslDefinition>,
+    ),
+}
+```
+
+**Registration in `Graph::new()`:**
+
+```rust
+impl Graph {
+    pub fn new() -> Self {
+        let mut graph = Self { /* ... */ dsl_processors: Vec::new() };
+
+        // Register built-in DSL processors
+        graph.register_dsl_processor(DslProcessor {
+            method_name: StringId::from("new"),
+            matches: class_new_matches,
+            handle: handle_class_new,
+        });
+        graph.register_dsl_processor(DslProcessor {
+            method_name: StringId::from("new"),
+            matches: module_new_matches,
+            handle: handle_module_new,
+        });
+
+        graph
+    }
+
+    pub fn register_dsl_processor(&mut self, processor: DslProcessor) {
+        self.dsl_processors.push(processor);
+    }
+
+    pub fn dsl_processors(&self) -> &[DslProcessor] {
+        &self.dsl_processors
+    }
+
+    /// Checks if a method name is a DSL target (derived from registered processors)
+    pub fn is_dsl_target(&self, method_name: &StringId) -> bool {
+        self.dsl_processors.iter().any(|p| p.method_name == *method_name)
+    }
+}
+```
+
+**Handler functions in `model/dsl_processors.rs`:**
+
+```rust
+pub fn class_new_matches(receiver_decl_id: Option<DeclarationId>, method_name: &str) -> bool {
+    receiver_decl_id == Some(*CLASS_ID) && method_name == "new"
+}
+
+pub fn handle_class_new(
+    graph: &mut Graph,
+    dsl_def: &DslDefinition,
+    const_to_dsl: Option<&ConstantToDslDefinition>,
+) {
+    // Extract constant_name from const_to_dsl (with reparenting logic)
+    // Extract superclass from dsl_def.arguments().positional_args().first()
+    // Create DynamicClassDefinition or fallback to ConstantDefinition
+    // Update member definitions' lexical_nesting_id
+}
 
-    /// Process the DSL and create new definitions/declarations
-    fn process(&self, graph: &mut Graph, dsl: &DslDefinition);
+pub fn module_new_matches(receiver_decl_id: Option<DeclarationId>, method_name: &str) -> bool {
+    receiver_decl_id == Some(*MODULE_ID) && method_name == "new"
 }
 
-struct DslHandlerRegistry {
-    handlers: Vec<Box<dyn DslHandler>>,
+pub fn handle_module_new(
+    graph: &mut Graph,
+    dsl_def: &DslDefinition,
+    const_to_dsl: Option<&ConstantToDslDefinition>,
+) {
+    // Similar to handle_class_new but creates DynamicModuleDefinition
 }
 ```
 
@@ -336,13 +436,14 @@ impl DynamicModuleDefinition {
 - Add `DslDefinition` struct
 - Add `ConstantToDslDefinition` struct
 - Add `DynamicClassDefinition` and `DynamicModuleDefinition` structs
-- Add `internal_dsl_targets` to Graph
+- Add `DslProcessor` struct and processor registry to Graph
+- Add `model/dsl_processors.rs` with handler functions
 - Add `index_dsl_definition_target` helper in indexer (similar to `index_constant_alias_target`)
 - Add `add_constant_to_dsl_definition` helper in indexer
 - Implement `Nesting::Dsl` variant for nesting stack
 - Add `process_dsl_definitions()` method for Phase 3
-- Implement `Class.new` handler
-- Implement `Module.new` handler
+- Implement `Class.new` processor (`class_new_matches`, `handle_class_new`)
+- Implement `Module.new` processor (`module_new_matches`, `handle_module_new`)
 
 ### Out of Scope
 
@@ -359,7 +460,7 @@ impl DynamicModuleDefinition {
 
 ## Test Cases
 
-1. **Unknown receiver fallback**:
+1. **Unknown receiver - no transformation**:
 
    ```ruby
    class MyClass
@@ -368,7 +469,7 @@ impl DynamicModuleDefinition {
    Foo = MyClass.new
    ```
 
-   `ConstantToDslDefinition(Foo)` should become `ConstantDefinition(Foo)` since `MyClass.new` doesn't match any handler.
+   No processor matches `MyClass.new`, so DSL stays as-is. The `ConstantToDslDefinition(Foo)` remains linked to the unprocessed `DslDefinition`.
 
 2. **Inheritance from dynamic class**:
 
@@ -391,4 +492,4 @@ impl DynamicModuleDefinition {
    end
    ```
 
-   Verify `Bar` is correctly handled as a nested constant (`Foo::Bar` with `inner` method). And `Foo` has `name` and `name=` methods.
+   Verify `Bar` is correctly handled as a nested constant (`Foo::Bar` with `inner` method). And `Foo` has `name` method from attr_accessor. Note: attr_accessor only creates getter declarations in this codebase.

rust/rubydex-sys/src/definition_api.rs

@@ -26,6 +26,10 @@ pub enum DefinitionKind {
     ClassVariable = 11,
     MethodAlias = 12,
     GlobalVariableAlias = 13,
+    Dsl = 14,
+    ConstantToDsl = 15,
+    DynamicClass = 16,
+    DynamicModule = 17,
 }
 
 pub(crate) fn map_definition_to_kind(defn: &Definition) -> DefinitionKind {
@@ -44,6 +48,10 @@ pub(crate) fn map_definition_to_kind(defn: &Definition) -> DefinitionKind {
         Definition::ClassVariable(_) => DefinitionKind::ClassVariable,
         Definition::MethodAlias(_) => DefinitionKind::MethodAlias,
         Definition::GlobalVariableAlias(_) => DefinitionKind::GlobalVariableAlias,
+        Definition::Dsl(_) => DefinitionKind::Dsl,
+        Definition::ConstantToDsl(_) => DefinitionKind::ConstantToDsl,
+        Definition::DynamicClass(_) => DefinitionKind::DynamicClass,
+        Definition::DynamicModule(_) => DefinitionKind::DynamicModule,
     }
 }
 

rust/rubydex-sys/src/graph_api.rs

@@ -157,6 +157,8 @@ pub extern "C" fn rdx_graph_resolve(pointer: GraphPointer) {
     with_mut_graph(pointer, |graph| {
         let mut resolver = Resolver::new(graph);
         resolver.resolve_all();
+        resolver.process_dsl_definitions();
+        resolver.resolve_all();
     });
 }
 
@@ -435,20 +437,27 @@ mod tests {
 
     #[test]
     fn names_are_untracked_after_resolving_constant() {
+        let graph = Graph::new();
+        let dsl_targets = graph.dsl_targets();
+        drop(graph);
+
         let mut indexer = RubyIndexer::new(
             "file:///foo.rb".into(),
             "
             class Foo
               BAR = 1
             end
             ",
+            dsl_targets,
         );
         indexer.index();
 
         let mut graph = Graph::new();
         graph.update(indexer.local_graph());
         let mut resolver = Resolver::new(&mut graph);
         resolver.resolve_all();
+        resolver.process_dsl_definitions();
+        resolver.resolve_all();
 
         assert_eq!(
             1,

rust/rubydex/src/diagnostic.rs

@@ -2,7 +2,7 @@
 use crate::model::document::Document;
 use crate::{model::ids::UriId, offset::Offset};
 
-#[derive(Debug)]
+#[derive(Debug, Clone)]
 pub struct Diagnostic {
     rule: Rule,
     uri_id: UriId,

rust/rubydex/src/indexing.rs

@@ -16,15 +16,22 @@ pub struct IndexingRubyFileJob {
     path: PathBuf,
     local_graph_tx: Sender<LocalGraph>,
     errors_tx: Sender<Errors>,
+    dsl_method_names: Vec<&'static str>,
 }
 
 impl IndexingRubyFileJob {
     #[must_use]
-    pub fn new(path: PathBuf, local_graph_tx: Sender<LocalGraph>, errors_tx: Sender<Errors>) -> Self {
+    pub fn new(
+        path: PathBuf,
+        local_graph_tx: Sender<LocalGraph>,
+        errors_tx: Sender<Errors>,
+        dsl_method_names: Vec<&'static str>,
+    ) -> Self {
         Self {
             path,
             local_graph_tx,
             errors_tx,
+            dsl_method_names,
         }
     }
 
@@ -55,7 +62,7 @@ impl Job for IndexingRubyFileJob {
             return;
         };
 
-        let mut ruby_indexer = RubyIndexer::new(url.to_string(), &source);
+        let mut ruby_indexer = RubyIndexer::new(url.to_string(), &source, self.dsl_method_names.clone());
         ruby_indexer.index();
 
         self.local_graph_tx
@@ -73,12 +80,14 @@ pub fn index_files(graph: &mut Graph, paths: Vec<PathBuf>) -> Vec<Errors> {
     let queue = Arc::new(JobQueue::new());
     let (local_graphs_tx, local_graphs_rx) = unbounded();
     let (errors_tx, errors_rx) = unbounded();
+    let dsl_method_names = graph.dsl_method_names();
 
     for path in paths {
         queue.push(Box::new(IndexingRubyFileJob::new(
             path,
             local_graphs_tx.clone(),
             errors_tx.clone(),
+            dsl_method_names.clone(),
         )));
     }