method-ray 0.1.8 → 0.1.10

data/core/src/analyzer/exceptions.rs

@@ -0,0 +1,168 @@
+//! Exceptions - begin/rescue/ensure type inference
+//!
+//! Collects types from each branch and merges them into a Union
+//! via edges into a single result Vertex.
+//! Applies the same MergeVertex pattern as conditionals.rs.
+
+use crate::env::{GlobalEnv, LocalEnv};
+use crate::graph::{ChangeSet, VertexId};
+use crate::types::Type;
+use ruby_prism::{BeginNode, RescueModifierNode, RescueNode};
+
+use super::bytes_to_name;
+use super::install::{install_node, install_statements};
+
+/// Process BeginNode: begin/rescue/else/ensure
+///
+/// Type aggregation rules:
+///   - No rescue clause: return begin body type directly
+///   - With else clause: else type + all rescue types → Union (begin body excluded)
+///   - Without else clause: begin body type + all rescue types → Union
+///   - Ensure clause: processed for side effects only, does not affect return type
+pub(crate) fn process_begin_node(
+    genv: &mut GlobalEnv,
+    lenv: &mut LocalEnv,
+    changes: &mut ChangeSet,
+    source: &str,
+    begin_node: &BeginNode,
+) -> Option<VertexId> {
+    let begin_vtx = begin_node
+        .statements()
+        .and_then(|s| install_statements(genv, lenv, changes, source, &s));
+
+    let result = if let Some(rescue_node) = begin_node.rescue_clause() {
+        let result_vtx = genv.new_vertex();
+
+        process_rescue_chain(genv, lenv, changes, source, &rescue_node, result_vtx);
+
+        if let Some(else_node) = begin_node.else_clause() {
+            // With else: else type replaces begin body type (Ruby spec)
+            let else_vtx = else_node
+                .statements()
+                .and_then(|s| install_statements(genv, lenv, changes, source, &s));
+            if let Some(vtx) = else_vtx {
+                genv.add_edge(vtx, result_vtx);
+            }
+        } else if let Some(vtx) = begin_vtx {
+            genv.add_edge(vtx, result_vtx);
+        }
+
+        Some(result_vtx)
+    } else {
+        begin_vtx
+    };
+
+    // Ensure: side effects only, does not affect return type
+    if let Some(ensure_node) = begin_node.ensure_clause() {
+        if let Some(stmts) = ensure_node.statements() {
+            let _ = install_statements(genv, lenv, changes, source, &stmts);
+        }
+    }
+
+    result
+}
+
+/// Process RescueNode chain recursively.
+/// Empty rescue body evaluates to nil.
+fn process_rescue_chain(
+    genv: &mut GlobalEnv,
+    lenv: &mut LocalEnv,
+    changes: &mut ChangeSet,
+    source: &str,
+    rescue_node: &RescueNode,
+    result_vtx: VertexId,
+) {
+    let body_vtx = process_rescue_body(genv, lenv, changes, source, rescue_node);
+    let vtx = body_vtx.unwrap_or_else(|| genv.new_source(Type::Nil));
+    genv.add_edge(vtx, result_vtx);
+
+    if let Some(next) = rescue_node.subsequent() {
+        process_rescue_chain(genv, lenv, changes, source, &next, result_vtx);
+    }
+}
+
+/// Extract the exception type from rescue node's exception class list.
+/// Falls back to StandardError when no exceptions are specified or none can be resolved.
+// TODO: Non-constant exception expressions (method calls, splats, variables) are silently skipped.
+fn extract_exception_type(rescue_node: &RescueNode) -> Type {
+    let types: Vec<Type> = rescue_node
+        .exceptions()
+        .iter()
+        .filter_map(|exc| super::definitions::extract_constant_path(&exc))
+        .map(|name| Type::instance(&name))
+        .collect();
+
+    if types.is_empty() {
+        Type::instance("StandardError")
+    } else {
+        Type::union_of(types)
+    }
+}
+
+/// Process a single RescueNode body.
+/// Registers the rescue variable (=> e), processes the body,
+/// then removes the variable from scope.
+fn process_rescue_body(
+    genv: &mut GlobalEnv,
+    lenv: &mut LocalEnv,
+    changes: &mut ChangeSet,
+    source: &str,
+    rescue_node: &RescueNode,
+) -> Option<VertexId> {
+    for exc in &rescue_node.exceptions() {
+        install_node(genv, lenv, changes, source, &exc);
+    }
+
+    // Save/restore rescue variable binding (=> e)
+    // TODO: Only LocalVariableTargetNode is handled; instance/global/class vars are not yet supported.
+    let var_binding = if let Some(ref_node) = rescue_node.reference() {
+        ref_node.as_local_variable_target_node().map(|target| {
+            let name = bytes_to_name(target.name().as_slice());
+            let saved = lenv.get_var(&name);
+            let exception_vtx = genv.new_vertex();
+            let exception_type = extract_exception_type(rescue_node);
+            let exception_src = genv.new_source(exception_type);
+            genv.add_edge(exception_src, exception_vtx);
+            lenv.new_var(name.clone(), exception_vtx);
+            (name, saved)
+        })
+    } else {
+        None
+    };
+
+    let body_vtx = rescue_node
+        .statements()
+        .and_then(|s| install_statements(genv, lenv, changes, source, &s));
+
+    if let Some((name, saved)) = var_binding {
+        match saved {
+            Some(prev_vtx) => lenv.new_var(name, prev_vtx),
+            None => lenv.remove_var(&name),
+        }
+    }
+
+    body_vtx
+}
+
+/// Process RescueModifierNode: `expression rescue rescue_expression`
+pub(crate) fn process_rescue_modifier_node(
+    genv: &mut GlobalEnv,
+    lenv: &mut LocalEnv,
+    changes: &mut ChangeSet,
+    source: &str,
+    node: &RescueModifierNode,
+) -> Option<VertexId> {
+    let result_vtx = genv.new_vertex();
+
+    let expr_vtx = install_node(genv, lenv, changes, source, &node.expression());
+    if let Some(vtx) = expr_vtx {
+        genv.add_edge(vtx, result_vtx);
+    }
+
+    let rescue_vtx = install_node(genv, lenv, changes, source, &node.rescue_expression());
+    if let Some(vtx) = rescue_vtx {
+        genv.add_edge(vtx, result_vtx);
+    }
+
+    Some(result_vtx)
+}

data/{rust → core}/src/analyzer/install.rs

@@ -15,10 +15,11 @@ use super::definitions::{process_class_node, process_def_node, process_module_no
 use super::exceptions::{process_begin_node, process_rescue_modifier_node};
 use super::dispatch::{dispatch_needs_child, dispatch_simple, process_needs_child, DispatchResult};
 use super::literals::install_literal_node;
-use super::loops::{process_until_node, process_while_node};
+use super::loops::{process_for_node, process_until_node, process_while_node};
 use super::operators::{process_and_node, process_or_node};
 use super::parentheses::process_parentheses_node;
 use super::returns::process_return_node;
+use super::super_calls;
 
 /// Build graph from AST (public API wrapper)
 pub struct AstInstaller<'a> {
@@ -89,12 +90,26 @@ pub(crate) fn install_node(
         return process_rescue_modifier_node(genv, lenv, changes, source, &rescue_modifier);
     }
 
+    // SuperNode: super(args) — explicit arguments
+    if let Some(super_node) = node.as_super_node() {
+        return super_calls::process_super_node(genv, lenv, changes, source, &super_node);
+    }
+    // ForwardingSuperNode: super — implicit argument forwarding
+    if let Some(fwd_super_node) = node.as_forwarding_super_node() {
+        return super_calls::process_forwarding_super_node(
+            genv, lenv, changes, source, &fwd_super_node,
+        );
+    }
+
     if let Some(while_node) = node.as_while_node() {
         return process_while_node(genv, lenv, changes, source, &while_node);
     }
     if let Some(until_node) = node.as_until_node() {
         return process_until_node(genv, lenv, changes, source, &until_node);
     }
+    if let Some(for_node) = node.as_for_node() {
+        return process_for_node(genv, lenv, changes, source, &for_node);
+    }
 
     if let Some(paren_node) = node.as_parentheses_node() {
         return process_parentheses_node(genv, lenv, changes, source, &paren_node);

data/{rust → core}/src/analyzer/literals.rs

@@ -118,13 +118,9 @@ fn install_array_literal_elements(
 
     let array_type = if element_types.is_empty() {
         Type::array()
-    } else if element_types.len() == 1 {
-        let elem_type = element_types.into_iter().next().unwrap();
-        Type::array_of(elem_type)
     } else {
         let types_vec: Vec<Type> = element_types.into_iter().collect();
-        let union_type = Type::Union(types_vec);
-        Type::array_of(union_type)
+        Type::array_of(Type::union_of(types_vec))
     };
 
     Some(genv.new_source(array_type))
@@ -176,18 +172,8 @@ fn install_hash_literal_elements(
     let hash_type = if key_types.is_empty() || value_types.is_empty() {
         Type::hash()
     } else {
-        let key_type = if key_types.len() == 1 {
-            key_types.into_iter().next().unwrap()
-        } else {
-            let types_vec: Vec<Type> = key_types.into_iter().collect();
-            Type::Union(types_vec)
-        };
-        let value_type = if value_types.len() == 1 {
-            value_types.into_iter().next().unwrap()
-        } else {
-            let types_vec: Vec<Type> = value_types.into_iter().collect();
-            Type::Union(types_vec)
-        };
+        let key_type = Type::union_of(key_types.into_iter().collect());
+        let value_type = Type::union_of(value_types.into_iter().collect());
         Type::hash_of(key_type, value_type)
     };
 
@@ -238,57 +224,3 @@ fn infer_range_element_type(
     }
     None
 }
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_install_string_literal() {
-        let mut genv = GlobalEnv::new();
-        let vtx = genv.new_source(Type::string());
-        assert_eq!(genv.get_source(vtx).unwrap().ty.show(), "String");
-    }
-
-    #[test]
-    fn test_install_integer_literal() {
-        let mut genv = GlobalEnv::new();
-        let vtx = genv.new_source(Type::integer());
-        assert_eq!(genv.get_source(vtx).unwrap().ty.show(), "Integer");
-    }
-
-    #[test]
-    fn test_install_float_literal() {
-        let mut genv = GlobalEnv::new();
-        let vtx = genv.new_source(Type::float());
-        assert_eq!(genv.get_source(vtx).unwrap().ty.show(), "Float");
-    }
-
-    #[test]
-    fn test_install_regexp_literal() {
-        let mut genv = GlobalEnv::new();
-        let vtx = genv.new_source(Type::regexp());
-        assert_eq!(genv.get_source(vtx).unwrap().ty.show(), "Regexp");
-    }
-
-    #[test]
-    fn test_install_interpolated_string_literal() {
-        let mut genv = GlobalEnv::new();
-        let vtx = genv.new_source(Type::string());
-        assert_eq!(genv.get_source(vtx).unwrap().ty.show(), "String");
-    }
-
-    #[test]
-    fn test_install_interpolated_symbol_literal() {
-        let mut genv = GlobalEnv::new();
-        let vtx = genv.new_source(Type::symbol());
-        assert_eq!(genv.get_source(vtx).unwrap().ty.show(), "Symbol");
-    }
-
-    #[test]
-    fn test_install_interpolated_regexp_literal() {
-        let mut genv = GlobalEnv::new();
-        let vtx = genv.new_source(Type::regexp());
-        assert_eq!(genv.get_source(vtx).unwrap().ty.show(), "Regexp");
-    }
-}

data/core/src/analyzer/loops.rs

@@ -0,0 +1,94 @@
+//! Loops - while/until loop type inference
+//!
+//! Ruby loop expressions evaluate to nil (except when break passes a value).
+//! Break value propagation is not yet supported.
+
+use crate::env::{GlobalEnv, LocalEnv};
+use crate::graph::{ChangeSet, VertexId};
+use crate::types::Type;
+use ruby_prism::{ForNode, UntilNode, WhileNode};
+
+use super::bytes_to_name;
+use super::install::{install_node, install_statements};
+
+/// Process WhileNode: `while predicate; statements; end`
+///
+/// Returns nil. Traverses predicate and body to register method calls
+/// and variable assignments in the type graph.
+pub(crate) fn process_while_node(
+    genv: &mut GlobalEnv,
+    lenv: &mut LocalEnv,
+    changes: &mut ChangeSet,
+    source: &str,
+    while_node: &WhileNode,
+) -> Option<VertexId> {
+    install_node(genv, lenv, changes, source, &while_node.predicate());
+
+    if let Some(stmts) = while_node.statements() {
+        install_statements(genv, lenv, changes, source, &stmts);
+    }
+
+    Some(genv.new_source(Type::Nil))
+}
+
+/// Process UntilNode: `until predicate; statements; end`
+///
+/// Returns nil. Traverses predicate and body to register method calls
+/// and variable assignments in the type graph.
+pub(crate) fn process_until_node(
+    genv: &mut GlobalEnv,
+    lenv: &mut LocalEnv,
+    changes: &mut ChangeSet,
+    source: &str,
+    until_node: &UntilNode,
+) -> Option<VertexId> {
+    install_node(genv, lenv, changes, source, &until_node.predicate());
+
+    if let Some(stmts) = until_node.statements() {
+        install_statements(genv, lenv, changes, source, &stmts);
+    }
+
+    Some(genv.new_source(Type::Nil))
+}
+
+/// Process ForNode: `for index in collection; statements; end`
+///
+/// Ruby's `for` does NOT create a new scope — the loop variable persists
+/// after the loop. This differs from `collection.each { |x| }` which
+/// creates a block scope.
+///
+/// Returns nil (consistent with while/until; Ruby's for returns the
+/// collection, but the return value is rarely used in practice).
+pub(crate) fn process_for_node(
+    genv: &mut GlobalEnv,
+    lenv: &mut LocalEnv,
+    changes: &mut ChangeSet,
+    source: &str,
+    for_node: &ForNode,
+) -> Option<VertexId> {
+    let collection_vtx = install_node(genv, lenv, changes, source, &for_node.collection());
+
+    // TODO: MultiTargetNode (e.g., `for a, b in [[1, "x"]]`) is not yet supported
+    if let Some(target) = for_node.index().as_local_variable_target_node() {
+        let name = bytes_to_name(target.name().as_slice());
+        let var_vtx = genv.new_vertex();
+
+        // Array[T] or Range[T] → loop var gets T
+        let elem_type = collection_vtx
+            .and_then(|vtx| genv.get_source(vtx))
+            .and_then(|src| src.ty.type_args())
+            .and_then(|args| args.first().cloned());
+        if let Some(ty) = elem_type {
+            let elem_src = genv.new_source(ty);
+            genv.add_edge(elem_src, var_vtx);
+        }
+
+        lenv.new_var(name, var_vtx);
+    }
+
+    if let Some(stmts) = for_node.statements() {
+        install_statements(genv, lenv, changes, source, &stmts);
+    }
+
+    Some(genv.new_source(Type::Nil))
+}

data/{rust → core}/src/analyzer/mod.rs

@@ -13,6 +13,7 @@ mod operators;
 mod parameters;
 mod parentheses;
 mod returns;
+mod super_calls;
 mod variables;
 
 pub use install::AstInstaller;
@@ -30,18 +31,3 @@ pub use install::AstInstaller;
 pub(crate) fn bytes_to_name(bytes: &[u8]) -> String {
     String::from_utf8_lossy(bytes).to_string()
 }
-
-#[cfg(test)]
-mod tests {
-    use super::bytes_to_name;
-
-    #[test]
-    fn test_bytes_to_name_valid_utf8() {
-        assert_eq!(bytes_to_name(b"hello"), "hello");
-    }
-
-    #[test]
-    fn test_bytes_to_name_invalid_utf8_replaced() {
-        assert_eq!(bytes_to_name(b"hello\xff"), "hello\u{FFFD}");
-    }
-}

data/core/src/analyzer/operators.rs

@@ -0,0 +1,79 @@
+//! Operators - logical operator type inference (&&, ||, !)
+
+use crate::env::{GlobalEnv, LocalEnv};
+use crate::graph::{ChangeSet, VertexId};
+use crate::types::Type;
+use ruby_prism::{AndNode, Node, OrNode};
+
+use super::install::install_node;
+
+/// Merge two branch nodes into a union type vertex.
+fn process_binary_logical_op<'a>(
+    genv: &mut GlobalEnv,
+    lenv: &mut LocalEnv,
+    changes: &mut ChangeSet,
+    source: &str,
+    left: Node<'a>,
+    right: Node<'a>,
+) -> Option<VertexId> {
+    let result_vtx = genv.new_vertex();
+
+    if let Some(vtx) = install_node(genv, lenv, changes, source, &left) {
+        genv.add_edge(vtx, result_vtx);
+    }
+
+    if let Some(vtx) = install_node(genv, lenv, changes, source, &right) {
+        genv.add_edge(vtx, result_vtx);
+    }
+
+    Some(result_vtx)
+}
+
+/// Process AndNode (a && b): Union(type(a), type(b))
+///
+/// Runtime: if `a` is falsy, returns `a`; otherwise returns `b`.
+/// Static: conservatively produce Union(type(a), type(b)).
+pub(crate) fn process_and_node(
+    genv: &mut GlobalEnv,
+    lenv: &mut LocalEnv,
+    changes: &mut ChangeSet,
+    source: &str,
+    and_node: &AndNode,
+) -> Option<VertexId> {
+    process_binary_logical_op(genv, lenv, changes, source, and_node.left(), and_node.right())
+}
+
+/// Process OrNode (a || b): Union(type(a), type(b))
+///
+/// Runtime: if `a` is truthy, returns `a`; otherwise returns `b`.
+/// Static: conservatively produce Union(type(a), type(b)).
+pub(crate) fn process_or_node(
+    genv: &mut GlobalEnv,
+    lenv: &mut LocalEnv,
+    changes: &mut ChangeSet,
+    source: &str,
+    or_node: &OrNode,
+) -> Option<VertexId> {
+    process_binary_logical_op(genv, lenv, changes, source, or_node.left(), or_node.right())
+}
+
+/// Process not operator (!expr): TrueClass | FalseClass
+///
+/// In ruby-prism, `!expr` is represented as a CallNode with method name "!".
+/// Static approximation: we cannot determine the receiver's truthiness at
+/// compile time, so conservatively return TrueClass | FalseClass for any `!` call.
+/// In practice, `!nil` and `!false` are always true, but we do not track that here.
+///
+/// Receiver side effects are already analyzed by the caller (process_needs_child).
+///
+/// TODO: Ruby allows overriding `BasicObject#!`. Currently we always return
+/// TrueClass | FalseClass, ignoring user-defined `!` methods. If needed, look up
+/// the receiver's RBS definition and use its return type instead.
+pub(crate) fn process_not_operator(genv: &mut GlobalEnv) -> VertexId {
+    let result_vtx = genv.new_vertex();
+    let true_vtx = genv.new_source(Type::instance("TrueClass"));
+    let false_vtx = genv.new_source(Type::instance("FalseClass"));
+    genv.add_edge(true_vtx, result_vtx);
+    genv.add_edge(false_vtx, result_vtx);
+    result_vtx
+}

data/{rust → core}/src/analyzer/parameters.rs

@@ -24,7 +24,7 @@ use super::bytes_to_name;
 ///   name.upcase
 /// end
 /// ```
-pub fn install_required_parameter(genv: &mut GlobalEnv, lenv: &mut LocalEnv, name: String) -> VertexId {
+pub(crate) fn install_required_parameter(genv: &mut GlobalEnv, lenv: &mut LocalEnv, name: String) -> VertexId {
     // Create a vertex for the parameter (starts as Bot/untyped)
     let param_vtx = genv.new_vertex();
 
@@ -44,7 +44,7 @@ pub fn install_required_parameter(genv: &mut GlobalEnv, lenv: &mut LocalEnv, nam
 ///   name.upcase
 /// end
 /// ```
-pub fn install_optional_parameter(
+pub(crate) fn install_optional_parameter(
     genv: &mut GlobalEnv,
     lenv: &mut LocalEnv,
     _changes: &mut ChangeSet,
@@ -75,7 +75,7 @@ pub fn install_optional_parameter(
 ///   items.first
 /// end
 /// ```
-pub fn install_rest_parameter(genv: &mut GlobalEnv, lenv: &mut LocalEnv, name: String) -> VertexId {
+pub(crate) fn install_rest_parameter(genv: &mut GlobalEnv, lenv: &mut LocalEnv, name: String) -> VertexId {
     // Create a vertex for the parameter
     let param_vtx = genv.new_vertex();
 
@@ -99,7 +99,7 @@ pub fn install_rest_parameter(genv: &mut GlobalEnv, lenv: &mut LocalEnv, name: S
 ///   options[:debug]
 /// end
 /// ```
-pub fn install_keyword_rest_parameter(
+pub(crate) fn install_keyword_rest_parameter(
     genv: &mut GlobalEnv,
     lenv: &mut LocalEnv,
     name: String,
@@ -204,66 +204,3 @@ pub(crate) fn install_parameters(
 
     (param_vtxs, keyword_param_vtxs)
 }
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_install_required_parameter() {
-        let mut genv = GlobalEnv::new();
-        let mut lenv = LocalEnv::new();
-
-        let vtx = install_required_parameter(&mut genv, &mut lenv, "name".to_string());
-
-        // Parameter should be registered in LocalEnv
-        assert_eq!(lenv.get_var("name"), Some(vtx));
-
-        // Vertex should exist in GlobalEnv (as untyped)
-        let vertex = genv.get_vertex(vtx);
-        assert!(vertex.is_some());
-    }
-
-    #[test]
-    fn test_install_multiple_parameters() {
-        let mut genv = GlobalEnv::new();
-        let mut lenv = LocalEnv::new();
-
-        let vtx_a = install_required_parameter(&mut genv, &mut lenv, "a".to_string());
-        let vtx_b = install_required_parameter(&mut genv, &mut lenv, "b".to_string());
-        let vtx_c = install_required_parameter(&mut genv, &mut lenv, "c".to_string());
-
-        // All parameters should be registered
-        assert_eq!(lenv.get_var("a"), Some(vtx_a));
-        assert_eq!(lenv.get_var("b"), Some(vtx_b));
-        assert_eq!(lenv.get_var("c"), Some(vtx_c));
-
-        // All vertices should be different
-        assert_ne!(vtx_a, vtx_b);
-        assert_ne!(vtx_b, vtx_c);
-        assert_ne!(vtx_a, vtx_c);
-    }
-
-    #[test]
-    fn test_install_optional_parameter_inherits_default_type() {
-        let mut genv = GlobalEnv::new();
-        let mut lenv = LocalEnv::new();
-        let mut changes = ChangeSet::new();
-
-        // Default value: 0 (Integer)
-        let default_vtx = genv.new_source(Type::integer());
-        let vtx = install_optional_parameter(
-            &mut genv,
-            &mut lenv,
-            &mut changes,
-            "age".to_string(),
-            default_vtx,
-        );
-
-        assert_eq!(lenv.get_var("age"), Some(vtx));
-
-        // Type should propagate from default value
-        let vertex = genv.get_vertex(vtx).unwrap();
-        assert_eq!(vertex.show(), "Integer");
-    }
-}

data/core/src/analyzer/parentheses.rs

@@ -0,0 +1,25 @@
+//! Parentheses - pass-through type propagation for parenthesized expressions
+
+use crate::env::{GlobalEnv, LocalEnv};
+use crate::graph::{ChangeSet, VertexId};
+
+use super::install::{install_node, install_statements};
+
+/// Process ParenthesesNode: propagate inner expression's type
+pub(crate) fn process_parentheses_node(
+    genv: &mut GlobalEnv,
+    lenv: &mut LocalEnv,
+    changes: &mut ChangeSet,
+    source: &str,
+    paren_node: &ruby_prism::ParenthesesNode,
+) -> Option<VertexId> {
+    let body = paren_node.body()?;
+
+    if let Some(stmts) = body.as_statements_node() {
+        // (expr1; expr2) → process all, return last expression's type
+        install_statements(genv, lenv, changes, source, &stmts)
+    } else {
+        // (expr) → propagate inner expression's type directly
+        install_node(genv, lenv, changes, source, &body)
+    }
+}

data/core/src/analyzer/returns.rs

@@ -0,0 +1,39 @@
+//! Return statement handling
+//!
+//! Processes `return expr` by connecting the expression's vertex
+//! to the enclosing method's merge vertex.
+
+use crate::env::{GlobalEnv, LocalEnv};
+use crate::graph::{ChangeSet, VertexId};
+
+use super::install::install_node;
+
+/// Process ReturnNode: connect return value to method's merge vertex
+pub(crate) fn process_return_node(
+    genv: &mut GlobalEnv,
+    lenv: &mut LocalEnv,
+    changes: &mut ChangeSet,
+    source: &str,
+    return_node: &ruby_prism::ReturnNode,
+) -> Option<VertexId> {
+    // Process return value (first argument only; multi-value return not yet supported)
+    let value_vtx = if let Some(arguments) = return_node.arguments() {
+        arguments
+            .arguments()
+            .iter()
+            .next()
+            .and_then(|arg| install_node(genv, lenv, changes, source, &arg))
+    } else {
+        // `return` without value → nil
+        Some(genv.new_source(crate::types::Type::Nil))
+    };
+
+    // Connect return value to method's merge vertex
+    if let Some(vtx) = value_vtx {
+        if let Some(merge_vtx) = genv.scope_manager.current_method_return_vertex() {
+            genv.add_edge(vtx, merge_vtx);
+        }
+    }
+
+    None
+}