Improve the plan structure

Author: st0012

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

@@ -49,7 +49,9 @@ struct DslDefinition {
 }
 ```
 
-The `DslDefinition` is pushed onto the nesting stack when visiting its block, so any definitions inside (methods, nested DSL calls, etc.) become members of the `DslDefinition` rather than the lexical parent.
+The `DslDefinition` is pushed onto the nesting stack (via new `Nesting::Dsl` variant) when visiting its block, so any definitions inside (methods, nested DSL calls, etc.) become members of the `DslDefinition` rather than the lexical parent.
+
+A `ConstantReference` is also created for `receiver_name` so it gets resolved naturally in Phase 2.
 
 #### ConstantToDslDefinition
 
@@ -77,14 +79,14 @@ For non-constant cases (`var = Class.new` or just `Class.new`), only `DslDefinit
 
 ### Phase 2: Resolution
 
-Standard resolution runs, which resolves `receiver_name` to a fully qualified name (e.g., `Class` in scope `Foo` → `::Class`).
+Standard resolution runs, which resolves `receiver_name` to a fully qualified name (e.g., `Class` in scope `Foo` → `::Class`). The `ConstantReference` created for `receiver_name` ensures it gets resolved through the normal reference resolution path.
 
-### Phase 3: DSL Processing (New Phase)
+### Phase 3: DSL Processing
 
-After resolution, process all `ConstantToDslDefinition`s:
+A new method `process_dsl_definitions()` is called after `resolve_all()`. It processes all `ConstantToDslDefinition`s:
 
 1. Look up the referenced `DslDefinition`
-2. Get the resolved receiver name
+2. Get the resolved receiver via `graph.names().get(&receiver_name)`
 3. Dispatch to handler based on resolved receiver + method name:
 
 ```text
@@ -98,11 +100,19 @@ resolved receiver = ::Module, method = "new" → ModuleNewHandler
 - **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.
 
-Each handler also decides what to do with owned members (reassign, discard, etc.).
+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.
 
 ### Phase 4: Incremental Resolution
 
-Run resolution again for any new definitions created in Phase 3. This should be fast since the set is small.
+Call `resolve_all()` again for any new definitions created in Phase 3. The full resolution approach is acceptable since the set of new definitions is small.
+
+**Full resolution flow:**
+
+```rust
+resolver.resolve_all();           // Phase 2
+resolver.process_dsl_definitions(); // Phase 3
+resolver.resolve_all();           // Phase 4
+```
 
 ## DslDefinition Details
 
@@ -129,7 +139,7 @@ struct DslArgumentList {
 
 ### 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:
+All DSL calls automatically own their block contents. This simplifies indexing logic - the handler decides what to do with owned definitions during processing:
 
 - Reassign them to a new owner
 - Discard them
@@ -138,7 +148,7 @@ All DSL calls automatically own their block contents. This simplifies indexing l
 
 ### Lifecycle
 
-`DslDefinition` is kept after processing. It shares a declaration with any generated definitions, enabling tooling features like "hover over `belongs_to` → see generated methods".
+`DslDefinition` is kept after processing. It shares a declaration with generated definitions, enabling tooling features like "hover over `belongs_to` → see generated methods".
 
 ## Example: Class.new
 
@@ -156,6 +166,7 @@ end
 - `DslDefinition(receiver: Name(Class), method: "new", members: [MethodDefinition(baz)])`
 - `ConstantToDslDefinition(constant: Bar, dsl: DslDefinition)` - links constant to DSL
 - `MethodDefinition(baz)` with lexical nesting pointing to DslDefinition
+- `ConstantReference` for `Class` (for receiver resolution)
 
 **Resolution:**
 
@@ -211,7 +222,7 @@ end
 
 **DSL Processing (via RSpec plugin):**
 
-- Plugin handler decides how to represent these—perhaps as test group declarations with the helper method scoped appropriately.
+- Plugin handler decides how to represent these - perhaps as test group declarations with the helper method scoped appropriately.
 
 ## New Types
 
@@ -245,7 +256,7 @@ struct DynamicClassDefinition {
     name_id: Option<NameId>,  // None for anonymous classes
     uri_id: UriId,
     offset: Offset,
-    members: Vec<DefinitionId>,  // Consistent with ClassDefinition
+    members: Vec<DefinitionId>,
     superclass_ref: Option<ReferenceId>,
     mixins: Vec<Mixin>,
     lexical_nesting_id: Option<DefinitionId>,
@@ -258,7 +269,7 @@ struct DynamicModuleDefinition {
     name_id: Option<NameId>,  // None for anonymous modules
     uri_id: UriId,
     offset: Offset,
-    members: Vec<DefinitionId>,  // Consistent with ModuleDefinition
+    members: Vec<DefinitionId>,
     mixins: Vec<Mixin>,
     lexical_nesting_id: Option<DefinitionId>,
     comments: Vec<Comment>,
@@ -291,8 +302,6 @@ struct DslHandlerRegistry {
 
 ### DefinitionId Generation
 
-`DslDefinition` generates its ID using receiver_name and method_name:
-
 ```rust
 impl DslDefinition {
     pub fn id(&self) -> DefinitionId {
@@ -305,11 +314,24 @@ impl DslDefinition {
         ))
     }
 }
+
+impl DynamicClassDefinition {
+    pub fn id(&self) -> DefinitionId {
+        // Same location as source DslDefinition, with "Class.new" suffix
+        DefinitionId::from(&format!("{}{}Class.new", *self.uri_id, self.offset.start()))
+    }
+}
+
+impl DynamicModuleDefinition {
+    pub fn id(&self) -> DefinitionId {
+        DefinitionId::from(&format!("{}{}Module.new", *self.uri_id, self.offset.start()))
+    }
+}
 ```
 
-## Implementation Scope
+## Scope
 
-### Phase 1 (This Issue)
+### In Scope (This Issue)
 
 - Add `DslDefinition` struct
 - Add `ConstantToDslDefinition` struct
@@ -318,12 +340,15 @@ impl DslDefinition {
 - 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 DSL processing phase with `DslHandler` trait
+- Add `process_dsl_definitions()` method for Phase 3
 - Implement `Class.new` handler
 - Implement `Module.new` handler
 
-### Future Work
+### Out of Scope
 
+- Conditional assignments (`Foo = cond ? Class.new : Module.new`)
+- Method chaining (`Class.new.freeze`)
+- Late assignment of anonymous classes (`klass = Class.new; Foo = klass`)
 - `Struct.new` handler (complex: inherits from Struct, generates accessor methods)
 - Plugin API for external DSL targets
 - RSpec/Minitest support via plugins
@@ -332,29 +357,7 @@ impl DslDefinition {
 
 1. **Memory impact**: One-to-many relationship between definitions and declarations. Monitor memory usage during implementation.
 
-## Design Decisions Made
-
-1. **Constant assignment detection**: Use `ConstantToDslDefinition` to link constants to DSL calls. Similar pattern to `index_constant_alias_target` in existing code. Detected in `visit_constant_write_node` via new `index_dsl_definition_target` helper.
-
-2. **Anonymous classes**: `DynamicClassDefinition` uses `name_id: Option<NameId>`. Named classes get `Some(name)` from `ConstantToDslDefinition`, anonymous classes get `None` and no declaration is created.
-
-3. **Declaration membership**: For `Bar = Class.new`, `Declaration(Foo::Bar)` contains two definitions: `DslDefinition` and `DynamicClassDefinition`. This enables tooling to trace generated code back to the DSL call.
-
-4. **Unknown receiver fallback**: If `ConstantToDslDefinition` references a DSL whose receiver doesn't match any handler (e.g., `Foo = SomeClass.new`), it becomes a regular `ConstantDefinition`.
-
-5. **lexical_nesting_id preservation**: When members are reassigned from `DslDefinition` to `DynamicClassDefinition`, their `lexical_nesting_id` is NOT updated. It preserves the lexical structure as written in source code.
-
-6. **Phase 4 resolution**: Simply call `resolve_all` again. The set of new definitions is small, so full resolution is acceptable.
-
-7. **Edge cases not handled**: Conditional assignments (`Foo = cond ? Class.new : Module.new`), method chaining (`Class.new.freeze`), and late assignment of anonymous classes (`klass = Class.new; Foo = klass`) are out of scope.
-
-8. **Phase 3 location**: New method `process_dsl_definitions()` called after `resolve_all()`. Caller does: `resolver.resolve_all(); resolver.process_dsl_definitions(); resolver.resolve_all();`
-
-9. **Receiver resolution**: During indexing, create a `ConstantReference` for `DslDefinition.receiver_name`. It gets resolved naturally in Phase 2. Phase 3 looks it up via `graph.names().get(&receiver_name)`.
-
-10. **DynamicClassDefinition ID**: Use same location as source `DslDefinition` with DSL name: `format!("{}{}Class.new", uri_id, offset)`. Similarly `Module.new` for `DynamicModuleDefinition`.
-
-## Test Cases Needed
+## Test Cases
 
 1. **Unknown receiver fallback**: