@grafema/util 0.3.0-beta

package/dist/queries/traceDataflow.js

@@ -0,0 +1,754 @@
+/**
+ * Dataflow BFS Tracing
+ *
+ * Full BFS-based dataflow analysis with 100% reachability.
+ * Forward: 8 heuristics for complete data flow propagation.
+ * Backward: structural descent + PA matching + THROWS propagation.
+ *
+ * Shared by MCP handler and CLI trace command.
+ *
+ * @module queries/traceDataflow
+ */
+// === CONSTANTS ===
+const MUTATION_METHODS = new Set([
+    'push', 'unshift', 'splice', 'set', 'add', 'append', 'insert', 'enqueue', 'prepend',
+]);
+const STRUCTURAL_EDGE_TYPES = ['HAS_PROPERTY', 'HAS_ELEMENT', 'HAS_CONSEQUENT', 'HAS_ALTERNATE'];
+// === SHARED HELPERS ===
+/** Resolve a node ID through REFERENCE → READS_FROM to reach the declaration. */
+async function resolveRef(db, nodeId) {
+    const node = await db.getNode(nodeId);
+    if (!node)
+        return null;
+    if (node.type === 'REFERENCE') {
+        const edges = await db.getOutgoingEdges(nodeId, ['READS_FROM']);
+        return edges.length > 0 ? edges[0].dst : null;
+    }
+    return nodeId;
+}
+/** Extract .index from edge metadata (PASSES_ARGUMENT/RECEIVES_ARGUMENT). */
+function edgeIndex(edge) {
+    if (edge.metadata && typeof edge.metadata.index === 'number')
+        return edge.metadata.index;
+    if (typeof edge.index === 'number')
+        return edge.index;
+    return undefined;
+}
+/** Check if two argument-index values match (undefined = wildcard). */
+function indexMatch(paIdx, raIdx) {
+    if (paIdx === undefined || raIdx === undefined)
+        return true;
+    return paIdx === raIdx;
+}
+/** Resolve a PROPERTY_ACCESS receiver chain: walk READS_FROM to find base var + dot-path. */
+async function resolveReceiverChain(db, paId) {
+    const pathParts = [];
+    let cur = paId;
+    const seen = new Set();
+    while (cur && !seen.has(cur)) {
+        seen.add(cur);
+        const rf = await db.getOutgoingEdges(cur, ['READS_FROM']);
+        if (!rf.length)
+            break;
+        const t = await db.getNode(rf[0].dst);
+        if (!t)
+            break;
+        cur = rf[0].dst;
+        if (t.type === 'PROPERTY_ACCESS') {
+            if (t.name)
+                pathParts.push(t.name);
+            continue;
+        }
+        if (t.type === 'REFERENCE') {
+            const re = await db.getOutgoingEdges(t.id, ['READS_FROM']);
+            if (re.length) {
+                const r = await db.getNode(re[0].dst);
+                if (r && (r.type === 'CONSTANT' || r.type === 'VARIABLE')) {
+                    return { base: r.id, path: pathParts.join('.') };
+                }
+            }
+            return null;
+        }
+        if (t.type === 'CONSTANT' || t.type === 'VARIABLE') {
+            return { base: t.id, path: pathParts.join('.') };
+        }
+        break;
+    }
+    return null;
+}
+/** Resolve dynamic callee: follow ASSIGNED_FROM/READS_FROM chains to find the actual FUNCTION. */
+async function resolveDynamicCallee(db, nodeId) {
+    const seen = new Set();
+    let cur = nodeId;
+    while (cur && !seen.has(cur)) {
+        seen.add(cur);
+        const n = await db.getNode(cur);
+        if (!n)
+            return null;
+        if (n.type === 'FUNCTION')
+            return cur;
+        if (n.type === 'REFERENCE') {
+            const rf = await db.getOutgoingEdges(cur, ['READS_FROM']);
+            if (rf.length) {
+                cur = rf[0].dst;
+                continue;
+            }
+            return null;
+        }
+        if (n.type === 'PARAMETER' || n.type === 'VARIABLE' || n.type === 'CONSTANT') {
+            const afs = await db.getOutgoingEdges(cur, ['ASSIGNED_FROM']);
+            for (const af of afs) {
+                const afN = await db.getNode(af.dst);
+                if (afN?.type === 'FUNCTION')
+                    return af.dst;
+                if (afN?.type === 'REFERENCE') {
+                    const result = await resolveDynamicCallee(db, af.dst);
+                    if (result)
+                        return result;
+                }
+            }
+            if (n.type === 'PARAMETER') {
+                const raIn = await db.getIncomingEdges(cur, ['RECEIVES_ARGUMENT']);
+                for (const ra of raIn) {
+                    const fnId = ra.src;
+                    const raIdx = edgeIndex(ra);
+                    for (const ci of await db.getIncomingEdges(fnId, ['CALLS'])) {
+                        const pas = await db.getOutgoingEdges(ci.src, ['PASSES_ARGUMENT']);
+                        for (const pa of pas) {
+                            if (!indexMatch(raIdx, edgeIndex(pa)))
+                                continue;
+                            const paN = await db.getNode(pa.dst);
+                            if (paN?.type === 'FUNCTION')
+                                return pa.dst;
+                            if (paN?.type === 'REFERENCE') {
+                                const result = await resolveDynamicCallee(db, pa.dst);
+                                if (result)
+                                    return result;
+                            }
+                        }
+                    }
+                }
+            }
+            return null;
+        }
+        if (n.type === 'PROPERTY_ACCESS') {
+            const rf = await db.getOutgoingEdges(cur, ['READS_FROM']);
+            if (rf.length) {
+                cur = rf[0].dst;
+                continue;
+            }
+            return null;
+        }
+        return null;
+    }
+    return null;
+}
+// === FORWARD BFS ===
+/**
+ * Forward BFS dataflow trace.
+ * Starting from a declaration node, finds all nodes where data flows TO.
+ * Returns all reached nodes (including the start node at index 0).
+ */
+export async function traceForwardBFS(db, startId, maxIterations) {
+    const visited = new Set();
+    const queue = [];
+    const reachedNodes = [];
+    function enq(id) {
+        if (id && !visited.has(id)) {
+            visited.add(id);
+            queue.push(id);
+        }
+    }
+    // Guard sets for helper functions
+    const processedCalls = new Set();
+    const processedFns = new Set();
+    const climbProcessed = new Set();
+    // Lazy indexes
+    let paReadByName = null;
+    let catchParamIds = null;
+    /** Lazy index: "file::receiverName" → CALL node IDs for method calls on that receiver. */
+    let callsByReceiver = null;
+    async function getPAReadByName() {
+        if (paReadByName)
+            return paReadByName;
+        paReadByName = new Map();
+        for await (const n of db.queryNodes({ type: 'PROPERTY_ACCESS' })) {
+            const wt = await db.getOutgoingEdges(n.id, ['WRITES_TO']);
+            if (wt.length === 0 && n.name) {
+                const chain = await resolveReceiverChain(db, n.id);
+                if (chain) {
+                    let list = paReadByName.get(n.name);
+                    if (!list) {
+                        list = [];
+                        paReadByName.set(n.name, list);
+                    }
+                    list.push({ id: n.id, base: chain.base, path: chain.path });
+                }
+            }
+        }
+        return paReadByName;
+    }
+    async function getCatchParams() {
+        if (catchParamIds)
+            return catchParamIds;
+        catchParamIds = [];
+        for await (const p of db.queryNodes({ type: 'PARAMETER' })) {
+            const decls = await db.getIncomingEdges(p.id, ['DECLARES']);
+            for (const d of decls) {
+                const scope = await db.getNode(d.src);
+                if (scope?.name === 'catch') {
+                    catchParamIds.push(p.id);
+                    break;
+                }
+            }
+        }
+        return catchParamIds;
+    }
+    /**
+     * Build index of CALL nodes keyed by "file::receiverName".
+     * Used to find method calls on a declaration when CALL→DERIVED_FROM→PA→READS_FROM→REF
+     * edges are missing. CALL names encode the receiver: "db.getNode" → receiver "db".
+     */
+    async function getCallsByReceiver() {
+        if (callsByReceiver)
+            return callsByReceiver;
+        callsByReceiver = new Map();
+        for await (const c of db.queryNodes({ type: 'CALL' })) {
+            if (c.name?.includes('.') && c.file) {
+                const dotIdx = c.name.indexOf('.');
+                const receiver = c.name.substring(0, dotIdx);
+                // Skip computed receivers like "<obj>.method"
+                if (receiver.startsWith('<'))
+                    continue;
+                const key = `${c.file}::${receiver}`;
+                let list = callsByReceiver.get(key);
+                if (!list) {
+                    list = [];
+                    callsByReceiver.set(key, list);
+                }
+                list.push(c.id);
+            }
+        }
+        return callsByReceiver;
+    }
+    // --- Helper: enqueue call result consumers ---
+    async function enqueueCallConsumers(callId) {
+        if (processedCalls.has(callId))
+            return;
+        processedCalls.add(callId);
+        for (const af of await db.getIncomingEdges(callId, ['ASSIGNED_FROM']))
+            enq(af.src);
+        // Structural climb
+        for (const se of await db.getIncomingEdges(callId, [...STRUCTURAL_EDGE_TYPES])) {
+            await enqueueClimb(se.src, 3);
+        }
+        // CALL result passed as arg to another CALL
+        for (const pa of await db.getIncomingEdges(callId, ['PASSES_ARGUMENT'])) {
+            for (const ce of await db.getOutgoingEdges(pa.src, ['CALLS'])) {
+                for (const ra of await db.getOutgoingEdges(ce.dst, ['RECEIVES_ARGUMENT']))
+                    enq(ra.dst);
+            }
+            // Mutation on call result
+            for (const df of await db.getOutgoingEdges(pa.src, ['DERIVED_FROM'])) {
+                const dfN = await db.getNode(df.dst);
+                if (dfN?.type === 'PROPERTY_ACCESS' && dfN.name && MUTATION_METHODS.has(dfN.name)) {
+                    for (const rf of await db.getOutgoingEdges(df.dst, ['READS_FROM'])) {
+                        enq(await resolveRef(db, rf.dst));
+                    }
+                }
+            }
+            // Outer call result
+            await enqueueCallConsumers(pa.src);
+        }
+        // Chained calls: another CALL uses this as callee (fn()())
+        for (const df of await db.getIncomingEdges(callId, ['DERIVED_FROM'])) {
+            const dfN = await db.getNode(df.src);
+            if (dfN?.type === 'CALL')
+                await enqueueCallConsumers(df.src);
+        }
+        // CALL result returned by FUNCTION
+        for (const ret of await db.getIncomingEdges(callId, ['RETURNS'])) {
+            await enqueueFnCallers(ret.src);
+        }
+        // CALL result read via PA (call().value)
+        for (const rf of await db.getIncomingEdges(callId, ['READS_FROM'])) {
+            const rfN = await db.getNode(rf.src);
+            if (rfN?.type === 'PROPERTY_ACCESS')
+                enq(rf.src);
+        }
+        // Dynamic callee resolution
+        const callsEdges = await db.getOutgoingEdges(callId, ['CALLS']);
+        let hasStaticCallee = false;
+        for (const ce of callsEdges) {
+            const ceN = await db.getNode(ce.dst);
+            if (ceN?.type === 'FUNCTION') {
+                hasStaticCallee = true;
+                break;
+            }
+        }
+        if (!hasStaticCallee) {
+            for (const df of await db.getOutgoingEdges(callId, ['DERIVED_FROM'])) {
+                const resolved = await resolveDynamicCallee(db, df.dst);
+                if (resolved) {
+                    for (const ra of await db.getOutgoingEdges(resolved, ['RECEIVES_ARGUMENT']))
+                        enq(ra.dst);
+                }
+            }
+            for (const ce of callsEdges) {
+                const ceN = await db.getNode(ce.dst);
+                if (ceN?.type === 'PARAMETER') {
+                    const resolved = await resolveDynamicCallee(db, ce.dst);
+                    if (resolved) {
+                        for (const ra of await db.getOutgoingEdges(resolved, ['RECEIVES_ARGUMENT']))
+                            enq(ra.dst);
+                    }
+                }
+            }
+        }
+        // Callback injection: if CALL passes a FUNCTION as argument, trace into callback params
+        for (const pa of await db.getOutgoingEdges(callId, ['PASSES_ARGUMENT'])) {
+            const paN = await db.getNode(pa.dst);
+            if (paN?.type === 'FUNCTION') {
+                for (const ra of await db.getOutgoingEdges(pa.dst, ['RECEIVES_ARGUMENT']))
+                    enq(ra.dst);
+            }
+        }
+    }
+    // --- Helper: enqueue callers of a function ---
+    async function enqueueFnCallers(fnId) {
+        if (processedFns.has(fnId))
+            return;
+        processedFns.add(fnId);
+        for (const ci of await db.getIncomingEdges(fnId, ['CALLS'])) {
+            await enqueueCallConsumers(ci.src);
+        }
+        for (const fpa of await db.getIncomingEdges(fnId, ['PASSES_ARGUMENT'])) {
+            await enqueueCallConsumers(fpa.src);
+        }
+        for (const faf of await db.getIncomingEdges(fnId, ['ASSIGNED_FROM'])) {
+            for (const vc of await db.getIncomingEdges(faf.src, ['CALLS'])) {
+                await enqueueCallConsumers(vc.src);
+            }
+        }
+        for (const df of await db.getIncomingEdges(fnId, ['DERIVED_FROM'])) {
+            const dfN = await db.getNode(df.src);
+            if (dfN?.type === 'CALL')
+                await enqueueCallConsumers(df.src);
+        }
+    }
+    // --- Helper: climb structural containers ---
+    async function enqueueClimb(nodeId, maxClimb) {
+        if (maxClimb <= 0 || climbProcessed.has(nodeId))
+            return;
+        climbProcessed.add(nodeId);
+        enq(nodeId);
+        for (const af of await db.getIncomingEdges(nodeId, ['ASSIGNED_FROM']))
+            enq(af.src);
+        for (const ret of await db.getIncomingEdges(nodeId, ['RETURNS']))
+            await enqueueFnCallers(ret.src);
+        for (const se of await db.getIncomingEdges(nodeId, [...STRUCTURAL_EDGE_TYPES, 'PASSES_ARGUMENT'])) {
+            await enqueueClimb(se.src, maxClimb - 1);
+        }
+    }
+    // --- Helper: follow PASSES_ARGUMENT to callee params + mutation + call result ---
+    async function followPassesArgument(pa) {
+        const callId = pa.src;
+        const paIdx = edgeIndex(pa);
+        // A. To params (with index matching)
+        for (const ce of await db.getOutgoingEdges(callId, ['CALLS'])) {
+            const raEdges = await db.getOutgoingEdges(ce.dst, ['RECEIVES_ARGUMENT']);
+            for (const ra of raEdges) {
+                if (!indexMatch(paIdx, edgeIndex(ra)))
+                    continue;
+                enq(ra.dst);
+            }
+        }
+        // B. Mutation detection
+        for (const df of await db.getOutgoingEdges(callId, ['DERIVED_FROM'])) {
+            const dfN = await db.getNode(df.dst);
+            if (dfN?.type === 'PROPERTY_ACCESS' && dfN.name && MUTATION_METHODS.has(dfN.name)) {
+                for (const rf of await db.getOutgoingEdges(df.dst, ['READS_FROM'])) {
+                    enq(await resolveRef(db, rf.dst));
+                }
+            }
+        }
+        // C. Call result consumers
+        await enqueueCallConsumers(callId);
+    }
+    // === Main BFS loop ===
+    enq(startId);
+    let iterations = 0;
+    while (queue.length > 0) {
+        const declId = queue.shift();
+        iterations++;
+        if (iterations > maxIterations)
+            break;
+        const node = await db.getNode(declId);
+        if (!node)
+            continue;
+        reachedNodes.push(node);
+        // --- 1. Follow refs that read this declaration ---
+        const refsToDecl = await db.getIncomingEdges(declId, ['READS_FROM']);
+        for (const refEdge of refsToDecl) {
+            const refId = refEdge.src;
+            // 1a. ASSIGNED_FROM incoming on ref
+            for (const af of await db.getIncomingEdges(refId, ['ASSIGNED_FROM']))
+                enq(af.src);
+            // 1b. WRITES_TO incoming on ref
+            for (const wt of await db.getIncomingEdges(refId, ['WRITES_TO'])) {
+                enq(await resolveRef(db, wt.src));
+            }
+            // 1c. PASSES_ARGUMENT incoming on ref
+            for (const pa of await db.getIncomingEdges(refId, ['PASSES_ARGUMENT'])) {
+                await followPassesArgument(pa);
+            }
+            // 1d. Structural climb
+            for (const se of await db.getIncomingEdges(refId, [...STRUCTURAL_EDGE_TYPES])) {
+                await enqueueClimb(se.src, 4);
+            }
+            // 1e. DERIVED_FROM incoming on ref: EXPRESSION/CALL uses this ref
+            for (const df of await db.getIncomingEdges(refId, ['DERIVED_FROM'])) {
+                const dfN = await db.getNode(df.src);
+                if (dfN) {
+                    if (dfN.type === 'EXPRESSION')
+                        enq(df.src);
+                    else if (dfN.type === 'CALL')
+                        await enqueueCallConsumers(df.src);
+                }
+            }
+            // 1f. RETURNS / YIELDS — enqueue function callers + function itself
+            for (const ret of await db.getIncomingEdges(refId, ['RETURNS'])) {
+                await enqueueFnCallers(ret.src);
+                enq(ret.src);
+            }
+            for (const y of await db.getIncomingEdges(refId, ['YIELDS'])) {
+                await enqueueFnCallers(y.src);
+                enq(y.src);
+            }
+            // 1g. THROWS → all catch PARAMETERs
+            const throwsEdges = await db.getIncomingEdges(refId, ['THROWS']);
+            if (throwsEdges.length > 0) {
+                const cps = await getCatchParams();
+                for (const cpId of cps)
+                    enq(cpId);
+            }
+            // 1h. ITERATES_OVER incoming on ref
+            for (const io of await db.getIncomingEdges(refId, ['ITERATES_OVER']))
+                enq(io.src);
+            // 1i. PA reads from ref (receiver chain)
+            for (const paRead of await db.getIncomingEdges(refId, ['READS_FROM'])) {
+                const paN = await db.getNode(paRead.src);
+                if (paN?.type === 'PROPERTY_ACCESS')
+                    enq(paRead.src);
+            }
+            // 1j. DERIVED_FROM incoming (CALL consumers)
+            for (const df of await db.getIncomingEdges(refId, ['DERIVED_FROM'])) {
+                const dfN = await db.getNode(df.src);
+                if (dfN?.type === 'CALL')
+                    await enqueueCallConsumers(df.src);
+            }
+        }
+        // --- 2. Direct edges on declaration ---
+        for (const hel of await db.getIncomingEdges(declId, ['HAS_ELEMENT']))
+            enq(hel.src);
+        for (const hp of await db.getIncomingEdges(declId, ['HAS_PROPERTY']))
+            enq(hp.src);
+        for (const ret of await db.getIncomingEdges(declId, ['RETURNS']))
+            await enqueueFnCallers(ret.src);
+        for (const y of await db.getIncomingEdges(declId, ['YIELDS']))
+            await enqueueFnCallers(y.src);
+        for (const io of await db.getIncomingEdges(declId, ['ITERATES_OVER']))
+            enq(io.src);
+        for (const af of await db.getIncomingEdges(declId, ['ASSIGNED_FROM']))
+            enq(af.src);
+        // WRITES_TO incoming on declaration
+        for (const wt of await db.getIncomingEdges(declId, ['WRITES_TO'])) {
+            enq(await resolveRef(db, wt.src));
+        }
+        // PASSES_ARGUMENT incoming on declaration
+        for (const pa of await db.getIncomingEdges(declId, ['PASSES_ARGUMENT'])) {
+            await followPassesArgument(pa);
+        }
+        // --- 2b. Method call receiver heuristic ---
+        // When graph lacks CALL→DERIVED_FROM→PA→READS_FROM→REF edges for method calls,
+        // use CALL naming convention ("db.getNode" → receiver "db") to find method calls
+        // on this declaration and trace their consumers.
+        if ((node.type === 'CONSTANT' || node.type === 'VARIABLE' || node.type === 'PARAMETER') && node.name && node.file) {
+            const idx = await getCallsByReceiver();
+            const key = `${node.file}::${node.name}`;
+            const methodCalls = idx.get(key);
+            if (methodCalls) {
+                for (const callId of methodCalls)
+                    enq(callId);
+            }
+        }
+        // --- 3. PA write→read propagation via receiver chain matching ---
+        if (node.type === 'PROPERTY_ACCESS') {
+            const myChain = await resolveReceiverChain(db, declId);
+            if (myChain) {
+                const wt = await db.getOutgoingEdges(declId, ['WRITES_TO']);
+                if (wt.length > 0 && node.name) {
+                    const idx = await getPAReadByName();
+                    const readers = idx.get(node.name) || [];
+                    for (const r of readers) {
+                        if (r.base === myChain.base && r.path === myChain.path)
+                            enq(r.id);
+                    }
+                }
+            }
+        }
+        // --- 4. DERIVED_FROM incoming on declaration ---
+        for (const df of await db.getIncomingEdges(declId, ['DERIVED_FROM'])) {
+            const dfN = await db.getNode(df.src);
+            if (dfN?.type === 'CALL')
+                await enqueueCallConsumers(df.src);
+            else if (dfN?.type === 'EXPRESSION')
+                enq(df.src);
+        }
+        // --- 5. FUNCTION type → enqueueFnCallers ---
+        if (node.type === 'FUNCTION')
+            await enqueueFnCallers(declId);
+        // --- 6. CALL type → enqueueCallConsumers ---
+        if (node.type === 'CALL')
+            await enqueueCallConsumers(declId);
+    }
+    return reachedNodes;
+}
+// === BACKWARD BFS ===
+/**
+ * Backward BFS dataflow trace.
+ * Starting from a declaration node, finds all nodes where data comes FROM.
+ * Returns all reached nodes (including the start node at index 0).
+ */
+export async function traceBackwardBFS(db, startId, maxIterations) {
+    const visited = new Set();
+    const queue = [];
+    const reachedNodes = [];
+    function enq(id) {
+        if (id && !visited.has(id)) {
+            visited.add(id);
+            queue.push(id);
+        }
+    }
+    // Lazy PA writer index
+    let paWriterByName = null;
+    async function getPAWriterByName() {
+        if (paWriterByName)
+            return paWriterByName;
+        paWriterByName = new Map();
+        for await (const n of db.queryNodes({ type: 'PROPERTY_ACCESS' })) {
+            const wt = await db.getOutgoingEdges(n.id, ['WRITES_TO']);
+            if (wt.length > 0 && n.name) {
+                const chain = await resolveReceiverChain(db, n.id);
+                if (chain) {
+                    let list = paWriterByName.get(n.name);
+                    if (!list) {
+                        list = [];
+                        paWriterByName.set(n.name, list);
+                    }
+                    list.push({ id: n.id, base: chain.base, path: chain.path });
+                }
+            }
+        }
+        return paWriterByName;
+    }
+    enq(startId);
+    let iterations = 0;
+    while (queue.length > 0) {
+        const nodeId = queue.shift();
+        iterations++;
+        if (iterations > maxIterations)
+            break;
+        const node = await db.getNode(nodeId);
+        if (!node)
+            continue;
+        reachedNodes.push(node);
+        // 1. ASSIGNED_FROM outgoing → resolve ref → enqueue source
+        for (const af of await db.getOutgoingEdges(nodeId, ['ASSIGNED_FROM'])) {
+            const src = await resolveRef(db, af.dst);
+            enq(src);
+            const afNode = await db.getNode(af.dst);
+            if (afNode && !['CONSTANT', 'VARIABLE', 'PARAMETER', 'REFERENCE'].includes(afNode.type)) {
+                for (const ch of await db.getOutgoingEdges(af.dst, [...STRUCTURAL_EDGE_TYPES])) {
+                    const resolved = await resolveRef(db, ch.dst);
+                    enq(resolved);
+                }
+            }
+        }
+        // 2. Refs that write to this node → trace back to what was written
+        const refsToNode = await db.getIncomingEdges(nodeId, ['READS_FROM']);
+        for (const refEdge of refsToNode) {
+            const wtEdges = await db.getOutgoingEdges(refEdge.src, ['WRITES_TO']);
+            for (const wt of wtEdges) {
+                const resolved = await resolveRef(db, wt.dst);
+                enq(resolved);
+            }
+        }
+        // 3. PARAMETER: incoming RECEIVES_ARGUMENT → FUNCTION → incoming CALLS → CALL → PASSES_ARGUMENT
+        if (node.type === 'PARAMETER') {
+            const raEdges = await db.getIncomingEdges(nodeId, ['RECEIVES_ARGUMENT']);
+            for (const ra of raEdges) {
+                const fnId = ra.src;
+                const raIdx = edgeIndex(ra);
+                const callsIn = await db.getIncomingEdges(fnId, ['CALLS']);
+                for (const callEdge of callsIn) {
+                    const paEdges = await db.getOutgoingEdges(callEdge.src, ['PASSES_ARGUMENT']);
+                    for (const pa of paEdges) {
+                        if (!indexMatch(raIdx, edgeIndex(pa)))
+                            continue;
+                        const argSrc = await resolveRef(db, pa.dst);
+                        enq(argSrc);
+                    }
+                }
+            }
+        }
+        // 4. Structural descent: outgoing HAS_ELEMENT, HAS_PROPERTY → descend, resolveRef
+        for (const ch of await db.getOutgoingEdges(nodeId, ['HAS_ELEMENT', 'HAS_PROPERTY'])) {
+            const resolved = await resolveRef(db, ch.dst);
+            enq(resolved);
+        }
+        // 5. CALL node: trace arguments and receiver chain
+        if (node.type === 'CALL') {
+            for (const pa of await db.getOutgoingEdges(nodeId, ['PASSES_ARGUMENT'])) {
+                const argSrc = await resolveRef(db, pa.dst);
+                enq(argSrc);
+            }
+            for (const df of await db.getOutgoingEdges(nodeId, ['DERIVED_FROM'])) {
+                const dfN = await db.getNode(df.dst);
+                if (dfN?.type === 'PROPERTY_ACCESS') {
+                    for (const rf of await db.getOutgoingEdges(df.dst, ['READS_FROM'])) {
+                        const resolved = await resolveRef(db, rf.dst);
+                        enq(resolved);
+                    }
+                }
+            }
+            // 5b. Receiver heuristic: when CALL→DERIVED_FROM→PA→READS_FROM chain is missing,
+            // parse receiver name from CALL name ("db.getNode" → "db") and find its declaration.
+            if (node.name?.includes('.')) {
+                const dotIdx = node.name.indexOf('.');
+                const receiverName = node.name.substring(0, dotIdx);
+                if (!receiverName.startsWith('<')) {
+                    for (const declType of ['CONSTANT', 'VARIABLE', 'PARAMETER']) {
+                        for await (const decl of db.queryNodes({ type: declType, name: receiverName })) {
+                            if (decl.file === node.file)
+                                enq(decl.id);
+                        }
+                    }
+                }
+            }
+        }
+        // 6. PA node: READS_FROM → resolveRef (the receiver's data source)
+        if (node.type === 'PROPERTY_ACCESS') {
+            for (const rf of await db.getOutgoingEdges(nodeId, ['READS_FROM'])) {
+                const resolved = await resolveRef(db, rf.dst);
+                enq(resolved);
+            }
+        }
+        // 7. ITERATES_OVER outgoing → resolveRef → enqueue (the iterable)
+        for (const io of await db.getOutgoingEdges(nodeId, ['ITERATES_OVER'])) {
+            const resolved = await resolveRef(db, io.dst);
+            enq(resolved);
+        }
+        // 8. Property read→write propagation: if this is a PA reader, find matching writers
+        if (node.type === 'PROPERTY_ACCESS' && node.name) {
+            const wt = await db.getOutgoingEdges(nodeId, ['WRITES_TO']);
+            if (wt.length === 0) {
+                const myChain = await resolveReceiverChain(db, nodeId);
+                if (myChain) {
+                    const idx = await getPAWriterByName();
+                    const writers = idx.get(node.name) || [];
+                    for (const w of writers) {
+                        if (w.base === myChain.base && w.path === myChain.path)
+                            enq(w.id);
+                    }
+                }
+            }
+        }
+        // 9. THROWS: if this is a catch PARAMETER, find thrown values
+        if (node.type === 'PARAMETER') {
+            const decls = await db.getIncomingEdges(nodeId, ['DECLARES']);
+            let isCatch = false;
+            for (const d of decls) {
+                const scope = await db.getNode(d.src);
+                if (scope?.name === 'catch') {
+                    isCatch = true;
+                    break;
+                }
+            }
+            if (isCatch) {
+                for await (const fn of db.queryNodes({ type: 'FUNCTION' })) {
+                    for (const t of await db.getOutgoingEdges(fn.id, ['THROWS'])) {
+                        const resolved = await resolveRef(db, t.dst);
+                        enq(resolved);
+                    }
+                }
+                for await (const mod of db.queryNodes({ type: 'MODULE' })) {
+                    for (const t of await db.getOutgoingEdges(mod.id, ['THROWS'])) {
+                        const resolved = await resolveRef(db, t.dst);
+                        enq(resolved);
+                    }
+                }
+            }
+        }
+        // 10. DERIVED_FROM outgoing: trace expression operands
+        for (const df of await db.getOutgoingEdges(nodeId, ['DERIVED_FROM'])) {
+            const resolved = await resolveRef(db, df.dst);
+            enq(resolved);
+        }
+        // 11. RETURNS incoming → if someone returns this node, trace the function's callers' arguments
+        for (const ret of await db.getIncomingEdges(nodeId, ['RETURNS'])) {
+            const callsIn = await db.getIncomingEdges(ret.src, ['CALLS']);
+            for (const callEdge of callsIn) {
+                for (const pa of await db.getOutgoingEdges(callEdge.src, ['PASSES_ARGUMENT'])) {
+                    const argSrc = await resolveRef(db, pa.dst);
+                    enq(argSrc);
+                }
+            }
+        }
+    }
+    return reachedNodes;
+}
+// === HIGH-LEVEL API ===
+/**
+ * Trace dataflow from a starting node.
+ * Handles REFERENCE resolution, runs BFS in requested direction(s).
+ * Returns results with start node excluded from reached lists.
+ */
+export async function traceDataflow(db, sourceId, options = {}) {
+    const { direction = 'forward', maxDepth = 10, limit } = options;
+    const maxIterations = Math.min((maxDepth || 10) * 100, 5000);
+    // Resolve REFERENCE to declaration
+    let startId = sourceId;
+    const sourceNode = await db.getNode(sourceId);
+    if (sourceNode?.type === 'REFERENCE') {
+        const edges = await db.getOutgoingEdges(sourceId, ['READS_FROM']);
+        if (edges.length > 0)
+            startId = edges[0].dst;
+    }
+    const resolvedStart = await db.getNode(startId);
+    if (!resolvedStart)
+        return [];
+    const results = [];
+    if (direction === 'forward' || direction === 'both') {
+        const nodes = await traceForwardBFS(db, startId, maxIterations);
+        const reached = nodes.slice(1); // skip start node
+        results.push({
+            direction: 'forward',
+            startNode: resolvedStart,
+            reached: limit ? reached.slice(0, limit) : reached,
+            totalReached: reached.length,
+        });
+    }
+    if (direction === 'backward' || direction === 'both') {
+        const nodes = await traceBackwardBFS(db, startId, maxIterations);
+        const reached = nodes.slice(1);
+        results.push({
+            direction: 'backward',
+            startNode: resolvedStart,
+            reached: limit ? reached.slice(0, limit) : reached,
+            totalReached: reached.length,
+        });
+    }
+    return results;
+}
+//# sourceMappingURL=traceDataflow.js.map