feat: Enable data flow analysis through function return values

This commit extends the cross-function analysis and type propagation engines to track variables across function boundaries via return values. Previously, analysis was limited to parameter passing; this change enables tracking data flow in factory patterns, getters, and chained calls (e.g., `x = create(); return x->field;`).

include/structor/cross_function_analyzer.hpp:
- Added `find_return_sources` to identify which variables are returned by a function, including pointer offsets.
- Added `find_return_assignments` to locate where a function call's return value is assigned to a local variable.
- Added `find_callers_with_return` to map a callee to specific variables in its callers.

src/cross_function_analyzer.cpp:
- Implemented `ReturnSourceFinder` visitor to parse `cit_return` instructions and extract `var + delta` arithmetic.
- Implemented `ReturnAssignmentFinder` visitor to parse `var = call(...)` patterns.
- Updated `trace_forward` to descend into callees when the tracked variable is assigned a return value.
- Updated `trace_backward` to ascend to callers when the tracked variable is returned, correctly applying pointer deltas.

include/structor/type_propagator.hpp:
- Updated `propagate_forward` to apply types to variables returned by called functions.
- Updated `propagate_backward` to propagate types from a returned variable to the caller's assignment target.
- Added AST visitors specific to type propagation for handling return flow logic.

integration_tests/test_callgraph_return.c:
- Added a new test suite covering factory functions (`make_root`), offset returns (`make_sub`), and complex call chains to verify pointer arithmetic handling across boundaries.

Impact:
- Significantly improves structure recovery for object-oriented C code and factory patterns.
- Analysis will now traverse deeper into the call graph, potentially increasing analysis time but yielding higher fidelity type reconstruction.
- Correctly handles pointer arithmetic on returns (e.g., returning a pointer to a struct member), preventing type confusion in sub-structs.

Author: 19h

include/structor/cross_function_analyzer.hpp

@@ -287,6 +287,15 @@ class CrossFunctionAnalyzer {
     /// Get or decompile a function (with caching)
     [[nodiscard]] cfuncptr_t get_cfunc(ea_t func_ea);
 
+    /// Collect return sources as (var_idx, delta) pairs
+    [[nodiscard]] qvector<std::pair<int, sval_t>> find_return_sources(cfunc_t* cfunc);
+
+    /// Find assignments of call return values in the current function
+    [[nodiscard]] qvector<std::pair<ea_t, int>> find_return_assignments(cfunc_t* cfunc);
+
+    /// Find callers that assign this function's return to a variable
+    [[nodiscard]] qvector<std::pair<ea_t, int>> find_callers_with_return(ea_t func_ea);
+
     /// Internal function cache to avoid redundant decompilation
     std::unordered_map<ea_t, cfuncptr_t> cfunc_cache_;
 };

include/structor/type_propagator.hpp

@@ -71,6 +71,14 @@ class TypePropagator {
         int var_idx,
         qvector<std::pair<ea_t, int>>& sources);
 
+    void find_return_sources(
+        cfunc_t* cfunc,
+        qvector<std::pair<int, sval_t>>& sources);
+
+    void find_callers_with_return(
+        ea_t func_ea,
+        qvector<std::pair<ea_t, int>>& callers);
+
     [[nodiscard]] bool is_parameter(cfunc_t* cfunc, int var_idx);
     [[nodiscard]] int get_param_index(cfunc_t* cfunc, int var_idx);
 
@@ -249,6 +257,45 @@ inline void TypePropagator::propagate_forward(
             result.add_failure(std::move(site));
         }
     }
+
+    // Propagate through return-value assignments: var = callee()
+    qvector<std::pair<ea_t, int>> return_sources;
+    find_assigned_from(cfunc, var_idx, return_sources);
+    for (const auto& [callee_ea, ret_marker] : return_sources) {
+        (void)ret_marker;
+        cfuncptr_t callee_cfunc = utils::get_cfunc(callee_ea);
+        if (!callee_cfunc) continue;
+
+        qvector<std::pair<int, sval_t>> return_vars;
+        find_return_sources(callee_cfunc, return_vars);
+
+        for (const auto& [return_var_idx, return_delta] : return_vars) {
+            (void)return_delta;
+            auto key = make_visit_key(callee_ea, return_var_idx);
+            if (visited_.count(key)) continue;
+            visited_.insert(key);
+
+            PropagationSite site;
+            site.func_ea = callee_ea;
+            site.var_idx = return_var_idx;
+            site.new_type = type;
+            site.direction = PropagationDirection::Forward;
+
+            lvars_t& callee_lvars = *callee_cfunc->get_lvars();
+            if (return_var_idx >= 0 && static_cast<size_t>(return_var_idx) < callee_lvars.size()) {
+                site.var_name = callee_lvars[return_var_idx].name;
+                site.old_type = callee_lvars[return_var_idx].type();
+            }
+
+            if (apply_type(callee_cfunc, return_var_idx, type)) {
+                result.add_success(std::move(site));
+                propagate_forward(callee_ea, return_var_idx, type, depth + 1, result);
+            } else {
+                site.failure_reason = "Failed to apply type";
+                result.add_failure(std::move(site));
+            }
+        }
+    }
 }
 
 inline void TypePropagator::propagate_backward(
@@ -263,6 +310,51 @@ inline void TypePropagator::propagate_backward(
     cfuncptr_t cfunc = utils::get_cfunc(func_ea);
     if (!cfunc) return;
 
+    // Propagate through return-value assignments: caller_var = func()
+    qvector<std::pair<int, sval_t>> return_vars;
+    find_return_sources(cfunc, return_vars);
+    for (const auto& [return_var_idx, return_delta] : return_vars) {
+        if (return_var_idx != var_idx) continue;
+        (void)return_delta;
+
+        qvector<std::pair<ea_t, int>> callers;
+        find_callers_with_return(func_ea, callers);
+
+        for (const auto& [caller_ea, caller_var_idx] : callers) {
+            auto key = make_visit_key(caller_ea, caller_var_idx);
+            if (visited_.count(key)) continue;
+            visited_.insert(key);
+
+            cfuncptr_t caller_cfunc = utils::get_cfunc(caller_ea);
+            if (!caller_cfunc) continue;
+
+            PropagationSite site;
+            site.func_ea = caller_ea;
+            site.var_idx = caller_var_idx;
+            site.new_type = type;
+            site.direction = PropagationDirection::Backward;
+
+            lvars_t& caller_lvars = *caller_cfunc->get_lvars();
+            if (caller_var_idx >= 0 && static_cast<size_t>(caller_var_idx) < caller_lvars.size()) {
+                site.var_name = caller_lvars[caller_var_idx].name;
+                site.old_type = caller_lvars[caller_var_idx].type();
+            }
+
+            if (apply_type(caller_cfunc, caller_var_idx, type)) {
+                result.add_success(std::move(site));
+
+                // Continue backward propagation
+                propagate_backward(caller_ea, caller_var_idx, type, depth + 1, result);
+
+                // Also propagate forward to reach siblings
+                propagate_forward(caller_ea, caller_var_idx, type, depth + 1, result);
+            } else {
+                site.failure_reason = "Failed to apply type";
+                result.add_failure(std::move(site));
+            }
+        }
+    }
+
     // Check if this is a parameter
     if (!is_parameter(cfunc, var_idx)) return;
 
@@ -542,6 +634,110 @@ inline void TypePropagator::find_assigned_from(
     visitor.apply_to(&cfunc->body, nullptr);
 }
 
+inline void TypePropagator::find_return_sources(
+    cfunc_t* cfunc,
+    qvector<std::pair<int, sval_t>>& sources)
+{
+    if (!cfunc) return;
+
+    struct ReturnVisitor : public ctree_visitor_t {
+        qvector<std::pair<int, sval_t>>& sources;
+
+        ReturnVisitor(qvector<std::pair<int, sval_t>>& s)
+            : ctree_visitor_t(CV_FAST)
+            , sources(s) {}
+
+        int idaapi visit_insn(cinsn_t* insn) override {
+            if (!insn || insn->op != cit_return) return 0;
+            if (!insn->creturn) return 0;
+
+            cexpr_t* expr = &insn->creturn->expr;
+            if (!expr || expr->op == cot_empty) return 0;
+
+            auto info = utils::extract_ptr_arith(expr);
+            if (!info.valid || info.var_idx < 0) return 0;
+
+            for (const auto& entry : sources) {
+                if (entry.first == info.var_idx && entry.second == info.offset) {
+                    return 0;
+                }
+            }
+
+            sources.push_back({info.var_idx, info.offset});
+            return 0;
+        }
+    };
+
+    ReturnVisitor visitor(sources);
+    visitor.apply_to(&cfunc->body, nullptr);
+}
+
+inline void TypePropagator::find_callers_with_return(
+    ea_t func_ea,
+    qvector<std::pair<ea_t, int>>& callers)
+{
+    qvector<ea_t> caller_funcs = utils::get_callers(func_ea);
+
+    for (ea_t caller_ea : caller_funcs) {
+        cfuncptr_t caller_cfunc = utils::get_cfunc(caller_ea);
+        if (!caller_cfunc) continue;
+
+        struct ReturnCallerFinder : public ctree_visitor_t {
+            ea_t target_func;
+            ea_t caller_ea;
+            qvector<std::pair<ea_t, int>>& results;
+
+            ReturnCallerFinder(ea_t func, ea_t caller, qvector<std::pair<ea_t, int>>& r)
+                : ctree_visitor_t(CV_FAST)
+                , target_func(func)
+                , caller_ea(caller)
+                , results(r) {}
+
+            static cexpr_t* find_base_var(cexpr_t* expr) {
+                while (expr) {
+                    if (expr->op == cot_var) return expr;
+                    if (expr->op == cot_cast || expr->op == cot_ref) {
+                        expr = expr->x;
+                    } else if (expr->op == cot_add || expr->op == cot_sub) {
+                        cexpr_t* left = find_base_var(expr->x);
+                        if (left) return left;
+                        expr = expr->y;
+                    } else if (expr->op == cot_memref || expr->op == cot_memptr) {
+                        expr = expr->x;
+                    } else if (expr->op == cot_idx) {
+                        expr = expr->x;
+                    } else {
+                        break;
+                    }
+                }
+                return nullptr;
+            }
+
+            int idaapi visit_expr(cexpr_t* expr) override {
+                if (!expr || expr->op != cot_asg) return 0;
+
+                cexpr_t* lhs = expr->x;
+                cexpr_t* rhs = expr->y;
+                while (rhs && rhs->op == cot_cast) {
+                    rhs = rhs->x;
+                }
+
+                if (!rhs || rhs->op != cot_call || !rhs->x) return 0;
+                if (rhs->x->op != cot_obj || rhs->x->obj_ea != target_func) return 0;
+
+                cexpr_t* base = find_base_var(lhs);
+                if (!base || base->op != cot_var) return 0;
+
+                results.push_back({caller_ea, base->v.idx});
+                return 0;
+            }
+        };
+
+        ReturnCallerFinder finder(func_ea, caller_ea, callers);
+        finder.apply_to(&caller_cfunc->body, nullptr);
+    }
+}
+
 inline bool TypePropagator::is_parameter(cfunc_t* cfunc, int var_idx) {
     if (!cfunc || var_idx < 0) return false;
 

integration_tests/test_callgraph_return.c

@@ -0,0 +1,136 @@
+#include <stdint.h>
+#include <stdio.h>
+
+static volatile uint64_t sink;
+
+#define OFF_MAGIC 0x00  // uint64_t
+#define OFF_FLAGS 0x08  // uint32_t / float (intentional conflict)
+#define OFF_MODE  0x0C  // uint16_t
+#define OFF_SCORE 0x10  // double
+#define OFF_KIND  0x18  // uint8_t
+#define OFF_SELF  0x20  // void*
+#define OFF_COUNT 0x28  // uint32_t
+#define OFF_ARR0  0x30  // uint64_t[3]
+#define OFF_ARR1  0x38
+#define OFF_ARR2  0x40
+#define OFF_CRC   0x48  // uint32_t
+#define OFF_BYTES 0x50  // uint8_t[8]
+#define OFF_SUB   0x60  // sub-struct base
+
+#define SUB_TAG   0x00  // uint32_t
+#define SUB_VALUE 0x08  // uint64_t
+#define SUB_STATE 0x10  // uint8_t
+
+__attribute__((noinline))
+void init_root(void *p) {
+    uint8_t *b = (uint8_t *)p;
+    *(uint64_t *)(b + OFF_MAGIC) = 0x1122334455667788ULL;
+    *(uint32_t *)(b + OFF_FLAGS) = 0xAABBCCDDU;
+    *(uint16_t *)(b + OFF_MODE) = 0x3344U;
+    *(double *)(b + OFF_SCORE) = 3.14159;
+    *(uint8_t *)(b + OFF_KIND) = 0x7FU;
+    *(void **)(b + OFF_SELF) = p;
+    *(uint32_t *)(b + OFF_COUNT) = 3U;
+
+    *(uint64_t *)(b + OFF_ARR0) = 0x1111111111111111ULL;
+    *(uint64_t *)(b + OFF_ARR1) = 0x2222222222222222ULL;
+    *(uint64_t *)(b + OFF_ARR2) = 0x3333333333333333ULL;
+
+    *(uint32_t *)(b + OFF_CRC) = 0xDEADBEAFU;
+
+    b[OFF_BYTES + 0] = 0x10;
+    b[OFF_BYTES + 1] = 0x20;
+    b[OFF_BYTES + 2] = 0x30;
+    b[OFF_BYTES + 3] = 0x40;
+
+    // Sub-struct at base + OFF_SUB
+    uint8_t *s = b + OFF_SUB;
+    *(uint32_t *)(s + SUB_TAG) = 0x1234U;
+    *(uint64_t *)(s + SUB_VALUE) = 0xCAFEBABECAFED00DULL;
+    *(uint8_t *)(s + SUB_STATE) = 0x5AU;
+}
+
+__attribute__((noinline))
+void process_root(void *p) {
+    uint8_t *b = (uint8_t *)p;
+    sink ^= *(uint64_t *)(b + OFF_MAGIC);
+    sink ^= *(uint32_t *)(b + OFF_FLAGS);
+    sink ^= *(uint16_t *)(b + OFF_MODE);
+    sink ^= (uint64_t)(*(uint8_t *)(b + OFF_KIND));
+    sink ^= *(uint64_t *)(b + OFF_ARR1);
+    sink ^= *(uint32_t *)(b + OFF_CRC);
+}
+
+__attribute__((noinline))
+void conflict_reader(void *p) {
+    uint8_t *b = (uint8_t *)p;
+    float f = *(float *)(b + OFF_FLAGS);
+    sink ^= (uint64_t)(*(uint32_t *)&f);
+}
+
+__attribute__((noinline))
+void sibling_reader(void *p) {
+    uint8_t *b = (uint8_t *)p;
+    sink ^= (uint64_t)(*(uint8_t *)(b + OFF_BYTES + 1));
+    sink ^= *(uint64_t *)(b + OFF_ARR2);
+}
+
+__attribute__((noinline))
+void process_sub(void *sub) {
+    uint8_t *s = (uint8_t *)sub;
+    sink ^= *(uint32_t *)(s + SUB_TAG);
+    sink ^= *(uint64_t *)(s + SUB_VALUE);
+    sink ^= (uint64_t)(*(uint8_t *)(s + SUB_STATE));
+}
+
+__attribute__((noinline))
+void wrapper_chain(void *p) {
+    process_root(p);
+    process_sub((uint8_t *)p + OFF_SUB);
+}
+
+__attribute__((noinline))
+void alias_forward(void *p) {
+    void *alias = p;
+    process_root(alias);
+}
+
+__attribute__((noinline))
+void *make_root(void) {
+    static uint8_t storage[0x80];
+    init_root(storage);
+    return storage;
+}
+
+__attribute__((noinline))
+void *make_sub(void *p) {
+    return (uint8_t *)p + OFF_SUB;
+}
+
+__attribute__((noinline))
+void chain_from_return(void) {
+    void *p = make_root();
+    process_root(p);
+    conflict_reader(p);
+    sibling_reader(p);
+
+    void *sub = make_sub(p);
+    process_sub(sub);
+}
+
+int main(void) {
+    uint8_t buf[0x80];
+
+    // Address-of pass to exercise cot_ref argument matching.
+    init_root(&buf);
+
+    wrapper_chain(buf);
+    sibling_reader(buf);
+    alias_forward(buf);
+    conflict_reader(buf);
+
+    chain_from_return();
+
+    printf("sink=%llx\n", (unsigned long long)sink);
+    return 0;
+}