@codeyam/codeyam-cli 0.1.0-staging.6e699e5 → 0.1.0-staging.73a4bf4

package/packages/ai/src/lib/dataStructure/ScopeDataStructure.js

@@ -79,6 +79,8 @@
  * - `helpers/README.md` - Overview of the helper module architecture
  */
 import fillInSchemaGapsAndUnknowns from "./helpers/fillInSchemaGapsAndUnknowns.js";
+import { clearCleanKnownObjectFunctionsCache } from "./helpers/cleanKnownObjectFunctions.js";
+import { clearCleanNonObjectFunctionsCache } from "./helpers/cleanNonObjectFunctions.js";
 /**
  * Patterns that indicate recursive type structures in schema paths.
  * Used by hasExcessivePatternRepetition() to detect exponential path blowup.
@@ -120,6 +122,17 @@ export function resetScopeDataStructureMetrics() {
     followEquivalenciesEarlyExitPhase1Count = 0;
     followEquivalenciesWithWorkCount = 0;
     addEquivalencyCallCount = 0;
+    // Clear module-level caches to prevent unbounded memory growth across entities
+    const knownObjectCache = clearCleanKnownObjectFunctionsCache();
+    const nonObjectCache = clearCleanNonObjectFunctionsCache();
+    if (knownObjectCache.count > 0 || nonObjectCache.count > 0) {
+        const totalBytes = knownObjectCache.estimatedBytes + nonObjectCache.estimatedBytes;
+        console.log('CodeYam: Cleared analysis caches', {
+            knownObjectCache: `${knownObjectCache.count} entries, ${(knownObjectCache.estimatedBytes / 1024).toFixed(1)}KB`,
+            nonObjectCache: `${nonObjectCache.count} entries, ${(nonObjectCache.estimatedBytes / 1024).toFixed(1)}KB`,
+            totalKB: `${(totalBytes / 1024).toFixed(1)}KB`,
+        });
+    }
 }
 // Performance: Pre-computed Sets for equivalency reason filtering (O(1) vs O(n))
 const ALLOWED_EQUIVALENCY_REASONS = new Set([
@@ -168,6 +181,7 @@ const SILENTLY_IGNORED_EQUIVALENCY_REASONS = new Set([
     'transformed non-object function equivalency - implicit parent equivalency - rerouted via useCallback',
     'transformed non-object function equivalency - Array.from() equivalency',
     'Spread operator equivalency key update: Explicit array deconstruction equivalency value',
+    // 'transformed non-object function equivalency - Explicit array deconstruction equivalency value',
 ]);
 export class ScopeDataStructure {
     // Getter for backward compatibility - returns the tree structure
@@ -462,6 +476,10 @@ export class ScopeDataStructure {
             }
             return;
         }
+        // PERF: Early exit for paths with repeated function-call signature patterns
+        if (this.hasExcessivePatternRepetition(path)) {
+            return;
+        }
         // Update chain metadata for database tracking
         if (equivalencyValueChain.length > 0) {
             equivalencyValueChain[equivalencyValueChain.length - 1].addToSchemaId =
@@ -958,6 +976,12 @@ export class ScopeDataStructure {
                     const value1 = scopeNode.schema[schemaPath];
                     const value2 = equivalentScopeNode.schema[equivalentSchemaPath];
                     const bestValue = selectBestValue(value1, value2);
+                    // PERF: Skip paths with repeated function-call signature patterns
+                    // to prevent recursive type expansion (e.g., string.localeCompare returns string)
+                    if (this.hasExcessivePatternRepetition(schemaPath) ||
+                        this.hasExcessivePatternRepetition(equivalentSchemaPath)) {
+                        continue;
+                    }
                     scopeNode.schema[schemaPath] = bestValue;
                     equivalentScopeNode.schema[equivalentSchemaPath] = bestValue;
                 }
@@ -969,6 +993,10 @@ export class ScopeDataStructure {
                         equivalentPath,
                         ...remainingSchemaPathParts,
                     ]);
+                    // PERF: Skip paths with repeated function-call signature patterns
+                    if (this.hasExcessivePatternRepetition(newEquivalentPath)) {
+                        continue;
+                    }
                     equivalentScopeNode.schema[newEquivalentPath] =
                         scopeNode.schema[schemaPath];
                 }
@@ -1050,6 +1078,23 @@ export class ScopeDataStructure {
                 return true;
             }
         }
+        // Check for repeated function calls that indicate recursive type expansion.
+        // E.g., localeCompare(b[])...localeCompare(b[]) means string.localeCompare
+        // returns a type that again has localeCompare, causing infinite expansion.
+        // We extract all function call patterns like "funcName(args)" and check if
+        // the same normalized call appears more than once.
+        const funcCallPattern = /(?:^|\.)[^.([]+\([^)]*\)/g;
+        const funcCallMatches = path.match(funcCallPattern);
+        if (funcCallMatches && funcCallMatches.length > 1) {
+            const seen = new Set();
+            for (const match of funcCallMatches) {
+                // Strip leading dot and normalize array indices
+                const normalized = match.replace(/^\./, '').replace(/\[\d+\]/g, '[]');
+                if (seen.has(normalized))
+                    return true;
+                seen.add(normalized);
+            }
+        }
         // For longer paths, detect any repeated multi-part segments we haven't explicitly listed
         const pathParts = this.splitPath(path);
         if (pathParts.length <= 6) {
@@ -1075,21 +1120,36 @@ export class ScopeDataStructure {
     }
     setInstantiatedVariables(scopeNode) {
         let instantiatedVariables = scopeNode.analysis?.instantiatedVariables ?? [];
-        for (const [path, equivalentPath] of Object.entries(scopeNode.analysis.isolatedEquivalentVariables ?? {})) {
-            if (typeof equivalentPath !== 'string') {
-                continue;
-            }
-            if (equivalentPath.startsWith('signature[')) {
-                const equivalentPathParts = this.splitPath(equivalentPath);
-                instantiatedVariables.push(equivalentPathParts[0]);
-                instantiatedVariables.push(path);
+        for (const [path, rawEquivalentPath] of Object.entries(scopeNode.analysis.isolatedEquivalentVariables ?? {})) {
+            // Normalize to array for consistent handling (supports both string and string[])
+            const equivalentPaths = Array.isArray(rawEquivalentPath)
+                ? rawEquivalentPath
+                : rawEquivalentPath
+                    ? [rawEquivalentPath]
+                    : [];
+            for (const equivalentPath of equivalentPaths) {
+                if (typeof equivalentPath !== 'string') {
+                    continue;
+                }
+                if (equivalentPath.startsWith('signature[')) {
+                    const equivalentPathParts = this.splitPath(equivalentPath);
+                    instantiatedVariables.push(equivalentPathParts[0]);
+                    instantiatedVariables.push(path);
+                }
             }
             const duplicateInstantiated = instantiatedVariables.find((v) => path.split('::cyDuplicateKey')[0] === v.split('::cyDuplicateKey')[0]);
             if (duplicateInstantiated) {
                 instantiatedVariables.push(path);
             }
         }
-        instantiatedVariables = instantiatedVariables.filter((varName, index, self) => self.indexOf(varName) === index);
+        const instantiatedSeen = new Set();
+        instantiatedVariables = instantiatedVariables.filter((varName) => {
+            if (instantiatedSeen.has(varName)) {
+                return false;
+            }
+            instantiatedSeen.add(varName);
+            return true;
+        });
         scopeNode.instantiatedVariables = instantiatedVariables;
         if (!scopeNode.tree || scopeNode.tree.length === 0) {
             return;
@@ -1101,9 +1161,16 @@ export class ScopeDataStructure {
         const parentInstantiatedVariables = [
             ...(parentScopeNode.parentInstantiatedVariables ?? []),
             ...parentScopeNode.instantiatedVariables.filter((v) => !v.startsWith('signature[') && !v.startsWith('returnValue')),
-        ].filter((varName, index, self) => !instantiatedVariables.includes(varName) &&
-            self.indexOf(varName) === index);
-        scopeNode.parentInstantiatedVariables = parentInstantiatedVariables;
+        ].filter((varName) => !instantiatedSeen.has(varName));
+        const parentInstantiatedSeen = new Set();
+        const dedupedParentInstantiatedVariables = parentInstantiatedVariables.filter((varName) => {
+            if (parentInstantiatedSeen.has(varName)) {
+                return false;
+            }
+            parentInstantiatedSeen.add(varName);
+            return true;
+        });
+        scopeNode.parentInstantiatedVariables = dedupedParentInstantiatedVariables;
     }
     trackFunctionCalls(scopeNode) {
         this.captureFunctionCalls(scopeNode);
@@ -1114,116 +1181,136 @@ export class ScopeDataStructure {
             return;
         }
         const { isolatedStructure, isolatedEquivalentVariables } = scopeNode.analysis;
+        // Flatten isolatedEquivalentVariables values for allPaths (handles both string and string[])
+        const flattenedEquivValues = Object.values(isolatedEquivalentVariables || {}).flatMap((v) => (Array.isArray(v) ? v : [v]));
         const allPaths = Array.from(new Set([
             ...Object.keys(isolatedStructure || {}),
             ...Object.keys(isolatedEquivalentVariables || {}),
-            ...Object.values(isolatedEquivalentVariables || {}),
+            ...flattenedEquivValues,
         ]));
         for (let path in isolatedEquivalentVariables) {
-            let equivalentValue = isolatedEquivalentVariables?.[path];
-            if (equivalentValue && this.isValidPath(equivalentValue)) {
-                // IMPORTANT: DO NOT strip ::cyDuplicateKey:: markers from equivalencies.
-                // These markers are critical for distinguishing variable reassignments.
-                // For example, with:
-                //   let fetcher = useFetcher<ConfigData>();
-                //   const configData = fetcher.data?.data;
-                //   fetcher = useFetcher<SettingsData>();
-                //   const settingsData = fetcher.data?.data;
-                //
-                // mergeStatements creates:
-                //   fetcher → useFetcher<ConfigData>()...
-                //   fetcher::cyDuplicateKey1:: → useFetcher<SettingsData>()...
-                //   configData → fetcher.data.data
-                //   settingsData → fetcher::cyDuplicateKey1::.data.data
-                //
-                // If we strip ::cyDuplicateKey::, settingsData would incorrectly trace
-                // to useFetcher<ConfigData>() instead of useFetcher<SettingsData>().
-                path = cleanPath(path, allPaths);
-                equivalentValue = cleanPath(equivalentValue, allPaths);
-                this.addEquivalency(path, equivalentValue, scopeNode.name, scopeNode, 'original equivalency');
-                // Propagate equivalencies involving parent-scope variables to those parent scopes.
-                // This handles patterns like: collected.push({...entity}) where 'collected' is defined
-                // in a parent scope. The equivalency collected[] -> push().signature[0] needs to be
-                // visible when tracing from the parent scope.
-                const rootVariable = this.extractRootVariable(path);
-                const equivalentRootVariable = this.extractRootVariable(equivalentValue);
-                // Skip propagation for self-referential reassignment patterns like:
-                //   x = x.method().functionCallReturnValue
-                // where the path IS the variable itself (not a sub-path like x[] or x.prop).
-                // These create circular references since both sides reference the same variable.
-                //
-                // But DO propagate for patterns like collected[] -> collected.push(...).signature[0]
-                // where the path has additional segments beyond the root variable.
-                const pathIsJustRootVariable = path === rootVariable;
-                const isSelfReferentialReassignment = pathIsJustRootVariable && rootVariable === equivalentRootVariable;
-                if (rootVariable &&
-                    !isSelfReferentialReassignment &&
-                    scopeNode.parentInstantiatedVariables?.includes(rootVariable)) {
-                    // Find the parent scope where this variable is defined
-                    for (const parentScopeName of scopeNode.tree || []) {
-                        const parentScope = this.scopeNodes[parentScopeName];
-                        if (parentScope?.instantiatedVariables?.includes(rootVariable)) {
-                            // Add the equivalency to the parent scope as well
-                            this.addEquivalency(path, equivalentValue, scopeNode.name, // The equivalent path's scope remains the child scope
-                            parentScope, // But store it in the parent scope's equivalencies
-                            'propagated parent-variable equivalency');
-                            break;
+            const rawEquivalentValue = isolatedEquivalentVariables?.[path];
+            // Normalize to array for consistent handling
+            const equivalentValues = Array.isArray(rawEquivalentValue)
+                ? rawEquivalentValue
+                : [rawEquivalentValue];
+            for (let equivalentValue of equivalentValues) {
+                if (equivalentValue && this.isValidPath(equivalentValue)) {
+                    // IMPORTANT: DO NOT strip ::cyDuplicateKey:: markers from equivalencies.
+                    // These markers are critical for distinguishing variable reassignments.
+                    // For example, with:
+                    //   let fetcher = useFetcher<ConfigData>();
+                    //   const configData = fetcher.data?.data;
+                    //   fetcher = useFetcher<SettingsData>();
+                    //   const settingsData = fetcher.data?.data;
+                    //
+                    // mergeStatements creates:
+                    //   fetcher → useFetcher<ConfigData>()...
+                    //   fetcher::cyDuplicateKey1:: → useFetcher<SettingsData>()...
+                    //   configData → fetcher.data.data
+                    //   settingsData → fetcher::cyDuplicateKey1::.data.data
+                    //
+                    // If we strip ::cyDuplicateKey::, settingsData would incorrectly trace
+                    // to useFetcher<ConfigData>() instead of useFetcher<SettingsData>().
+                    path = cleanPath(path, allPaths);
+                    equivalentValue = cleanPath(equivalentValue, allPaths);
+                    this.addEquivalency(path, equivalentValue, scopeNode.name, scopeNode, 'original equivalency');
+                    // Propagate equivalencies involving parent-scope variables to those parent scopes.
+                    // This handles patterns like: collected.push({...entity}) where 'collected' is defined
+                    // in a parent scope. The equivalency collected[] -> push().signature[0] needs to be
+                    // visible when tracing from the parent scope.
+                    const rootVariable = this.extractRootVariable(path);
+                    const equivalentRootVariable = this.extractRootVariable(equivalentValue);
+                    // Skip propagation for self-referential reassignment patterns like:
+                    //   x = x.method().functionCallReturnValue
+                    // where the path IS the variable itself (not a sub-path like x[] or x.prop).
+                    // These create circular references since both sides reference the same variable.
+                    //
+                    // But DO propagate for patterns like collected[] -> collected.push(...).signature[0]
+                    // where the path has additional segments beyond the root variable.
+                    const pathIsJustRootVariable = path === rootVariable;
+                    const isSelfReferentialReassignment = pathIsJustRootVariable && rootVariable === equivalentRootVariable;
+                    if (rootVariable &&
+                        !isSelfReferentialReassignment &&
+                        scopeNode.parentInstantiatedVariables?.includes(rootVariable)) {
+                        // Find the parent scope where this variable is defined
+                        for (const parentScopeName of scopeNode.tree || []) {
+                            const parentScope = this.scopeNodes[parentScopeName];
+                            if (parentScope?.instantiatedVariables?.includes(rootVariable)) {
+                                // Add the equivalency to the parent scope as well
+                                this.addEquivalency(path, equivalentValue, scopeNode.name, // The equivalent path's scope remains the child scope
+                                parentScope, // But store it in the parent scope's equivalencies
+                                'propagated parent-variable equivalency');
+                                break;
+                            }
                         }
                     }
-                }
-                // Propagate sub-property equivalencies when the equivalentValue is a simple variable
-                // that has sub-properties defined in the isolatedEquivalentVariables.
-                // This handles cases like: dataItem={{ structure: completeDataStructure }}
-                // where completeDataStructure has sub-properties like completeDataStructure['Function Arguments']
-                // We need to propagate these to create: dataItem.structure['Function Arguments'] equivalencies
-                const isSimpleVariable = !equivalentValue.startsWith('signature[') &&
-                    !equivalentValue.includes('functionCallReturnValue') &&
-                    !equivalentValue.includes('.') &&
-                    !equivalentValue.includes('[');
-                if (isSimpleVariable) {
-                    // Look in current scope and all parent scopes for sub-properties
-                    const scopesToCheck = [scopeNode.name, ...scopeNode.tree];
-                    for (const scopeName of scopesToCheck) {
-                        const checkScope = this.scopeNodes[scopeName];
-                        if (!checkScope?.analysis?.isolatedEquivalentVariables)
-                            continue;
-                        for (const [subPath, subValue] of Object.entries(checkScope.analysis.isolatedEquivalentVariables)) {
-                            // Check if this is a sub-property of the equivalentValue variable
-                            // e.g., completeDataStructure['Function Arguments'] or completeDataStructure.foo
-                            const matchesDot = subPath.startsWith(equivalentValue + '.');
-                            const matchesBracket = subPath.startsWith(equivalentValue + '[');
-                            if (matchesDot || matchesBracket) {
-                                const subPropertyPath = subPath.substring(equivalentValue.length);
-                                const newPath = cleanPath(path + subPropertyPath, allPaths);
-                                const newEquivalentValue = cleanPath(subValue.replace(/::cyDuplicateKey\d+::/g, ''), allPaths);
-                                if (newEquivalentValue &&
-                                    this.isValidPath(newEquivalentValue)) {
-                                    this.addEquivalency(newPath, newEquivalentValue, checkScope.name, // Use the scope where the sub-property was found
-                                    scopeNode, 'propagated sub-property equivalency');
+                    // Propagate sub-property equivalencies when the equivalentValue is a simple variable
+                    // that has sub-properties defined in the isolatedEquivalentVariables.
+                    // This handles cases like: dataItem={{ structure: completeDataStructure }}
+                    // where completeDataStructure has sub-properties like completeDataStructure['Function Arguments']
+                    // We need to propagate these to create: dataItem.structure['Function Arguments'] equivalencies
+                    const isSimpleVariable = !equivalentValue.startsWith('signature[') &&
+                        !equivalentValue.includes('functionCallReturnValue') &&
+                        !equivalentValue.includes('.') &&
+                        !equivalentValue.includes('[');
+                    if (isSimpleVariable) {
+                        // Look in current scope and all parent scopes for sub-properties
+                        const scopesToCheck = [scopeNode.name, ...scopeNode.tree];
+                        for (const scopeName of scopesToCheck) {
+                            const checkScope = this.scopeNodes[scopeName];
+                            if (!checkScope?.analysis?.isolatedEquivalentVariables)
+                                continue;
+                            for (const [subPath, rawSubValue] of Object.entries(checkScope.analysis.isolatedEquivalentVariables)) {
+                                // Normalize to array for consistent handling
+                                const subValues = Array.isArray(rawSubValue)
+                                    ? rawSubValue
+                                    : rawSubValue
+                                        ? [rawSubValue]
+                                        : [];
+                                // Check if this is a sub-property of the equivalentValue variable
+                                // e.g., completeDataStructure['Function Arguments'] or completeDataStructure.foo
+                                const matchesDot = subPath.startsWith(equivalentValue + '.');
+                                const matchesBracket = subPath.startsWith(equivalentValue + '[');
+                                if (matchesDot || matchesBracket) {
+                                    const subPropertyPath = subPath.substring(equivalentValue.length);
+                                    const newPath = cleanPath(path + subPropertyPath, allPaths);
+                                    for (const subValue of subValues) {
+                                        if (typeof subValue !== 'string')
+                                            continue;
+                                        const newEquivalentValue = cleanPath(subValue.replace(/::cyDuplicateKey\d+::/g, ''), allPaths);
+                                        if (newEquivalentValue &&
+                                            this.isValidPath(newEquivalentValue)) {
+                                            this.addEquivalency(newPath, newEquivalentValue, checkScope.name, // Use the scope where the sub-property was found
+                                            scopeNode, 'propagated sub-property equivalency');
+                                        }
+                                    }
+                                }
+                                // Also check if equivalentValue itself maps to a functionCallReturnValue
+                                // e.g., result = useMemo(...).functionCallReturnValue
+                                for (const subValue of subValues) {
+                                    if (subPath === equivalentValue &&
+                                        typeof subValue === 'string' &&
+                                        subValue.endsWith('.functionCallReturnValue')) {
+                                        this.propagateFunctionCallReturnSubProperties(path, subValue, scopeNode, allPaths);
+                                    }
                                 }
-                            }
-                            // Also check if equivalentValue itself maps to a functionCallReturnValue
-                            // e.g., result = useMemo(...).functionCallReturnValue
-                            if (subPath === equivalentValue &&
-                                typeof subValue === 'string' &&
-                                subValue.endsWith('.functionCallReturnValue')) {
-                                this.propagateFunctionCallReturnSubProperties(path, subValue, scopeNode, allPaths);
                             }
                         }
                     }
-                }
-                // Handle function call return values by propagating returnValue.* sub-properties
-                // from the callback scope to the usage path
-                if (equivalentValue.endsWith('.functionCallReturnValue')) {
-                    this.propagateFunctionCallReturnSubProperties(path, equivalentValue, scopeNode, allPaths);
-                    // Track which variable receives the return value of each function call
-                    // This enables generating separate mock data for each call site
-                    this.trackReceivingVariable(path, equivalentValue);
-                }
-                // Also track variables that receive destructured properties from function call return values
-                // e.g., "userData" -> "db.query('users').functionCallReturnValue.data"
-                if (equivalentValue.includes('.functionCallReturnValue.')) {
-                    this.trackReceivingVariable(path, equivalentValue);
+                    // Handle function call return values by propagating returnValue.* sub-properties
+                    // from the callback scope to the usage path
+                    if (equivalentValue.endsWith('.functionCallReturnValue')) {
+                        this.propagateFunctionCallReturnSubProperties(path, equivalentValue, scopeNode, allPaths);
+                        // Track which variable receives the return value of each function call
+                        // This enables generating separate mock data for each call site
+                        this.trackReceivingVariable(path, equivalentValue);
+                    }
+                    // Also track variables that receive destructured properties from function call return values
+                    // e.g., "userData" -> "db.query('users').functionCallReturnValue.data"
+                    if (equivalentValue.includes('.functionCallReturnValue.')) {
+                        this.trackReceivingVariable(path, equivalentValue);
+                    }
                 }
             }
         }
@@ -1367,8 +1454,15 @@ export class ScopeDataStructure {
                 const checkScope = this.scopeNodes[scopeName];
                 if (!checkScope?.analysis?.isolatedEquivalentVariables)
                     continue;
-                const functionRef = checkScope.analysis.isolatedEquivalentVariables[functionName];
-                if (typeof functionRef === 'string' && functionRef.endsWith('F')) {
+                const rawFunctionRef = checkScope.analysis.isolatedEquivalentVariables[functionName];
+                // Normalize to array and find first string ending with 'F'
+                const functionRefs = Array.isArray(rawFunctionRef)
+                    ? rawFunctionRef
+                    : rawFunctionRef
+                        ? [rawFunctionRef]
+                        : [];
+                const functionRef = functionRefs.find((r) => typeof r === 'string' && r.endsWith('F'));
+                if (typeof functionRef === 'string') {
                     callbackScopeName = functionRef.slice(0, -1);
                     break;
                 }
@@ -1391,22 +1485,32 @@ export class ScopeDataStructure {
         if (!callbackScope.analysis?.isolatedEquivalentVariables)
             return;
         const isolatedVars = callbackScope.analysis.isolatedEquivalentVariables;
+        // Get the first returnValue equivalency (normalize array to single value for these checks)
+        const rawReturnValue = isolatedVars.returnValue;
+        const firstReturnValue = Array.isArray(rawReturnValue)
+            ? rawReturnValue[0]
+            : rawReturnValue;
         // First, check if returnValue is an alias to another variable (e.g., returnValue = intermediate)
         // If so, we need to look for that variable's sub-properties too
-        const returnValueAlias = typeof isolatedVars.returnValue === 'string' &&
-            !isolatedVars.returnValue.includes('.')
-            ? isolatedVars.returnValue
+        const returnValueAlias = typeof firstReturnValue === 'string' && !firstReturnValue.includes('.')
+            ? firstReturnValue
             : undefined;
         // Pattern 3: Object.keys(X).reduce() - the reduce result has the same sub-properties as X
         // When returnValue = "Object.keys(source).reduce(...).functionCallReturnValue", look for source.* sub-properties
         let reduceSourceVar;
-        if (typeof isolatedVars.returnValue === 'string') {
-            const reduceMatch = isolatedVars.returnValue.match(/^Object\.keys\((\w+)\)\.reduce\(.*\)\.functionCallReturnValue$/);
+        if (typeof firstReturnValue === 'string') {
+            const reduceMatch = firstReturnValue.match(/^Object\.keys\((\w+)\)\.reduce\(.*\)\.functionCallReturnValue$/);
             if (reduceMatch) {
                 reduceSourceVar = reduceMatch[1];
             }
         }
-        for (const [subPath, subValue] of Object.entries(isolatedVars)) {
+        for (const [subPath, rawSubValue] of Object.entries(isolatedVars)) {
+            // Normalize to array for consistent handling
+            const subValues = Array.isArray(rawSubValue)
+                ? rawSubValue
+                : rawSubValue
+                    ? [rawSubValue]
+                    : [];
             // Check for direct returnValue.* sub-properties
             const isReturnValueSub = subPath.startsWith('returnValue.') ||
                 subPath.startsWith('returnValue[');
@@ -1418,33 +1522,36 @@ export class ScopeDataStructure {
             const isReduceSourceSub = reduceSourceVar &&
                 (subPath.startsWith(reduceSourceVar + '.') ||
                     subPath.startsWith(reduceSourceVar + '['));
-            if (typeof subValue !== 'string' ||
-                (!isReturnValueSub && !isAliasSub && !isReduceSourceSub))
-                continue;
-            // Convert alias/reduceSource paths to returnValue paths
-            let effectiveSubPath = subPath;
-            if (isAliasSub && !isReturnValueSub) {
-                // Replace the alias prefix with returnValue
-                effectiveSubPath =
-                    'returnValue' + subPath.substring(returnValueAlias.length);
-            }
-            else if (isReduceSourceSub && !isReturnValueSub && !isAliasSub) {
-                // Replace the reduce source prefix with returnValue
-                effectiveSubPath =
-                    'returnValue' + subPath.substring(reduceSourceVar.length);
-            }
-            const subPropertyPath = effectiveSubPath.substring('returnValue'.length);
-            const newPath = cleanPath(path + subPropertyPath, allPaths);
-            let newEquivalentValue = cleanPath(subValue.replace(/::cyDuplicateKey\d+::/g, ''), allPaths);
-            // Resolve variable references through parent scope equivalencies
-            const resolved = this.resolveVariableThroughParentScopes(newEquivalentValue, callbackScope, allPaths);
-            newEquivalentValue = resolved.resolvedPath;
-            const equivalentScopeName = resolved.scopeName;
-            if (!newEquivalentValue || !this.isValidPath(newEquivalentValue))
+            if (!isReturnValueSub && !isAliasSub && !isReduceSourceSub)
                 continue;
-            this.addEquivalency(newPath, newEquivalentValue, equivalentScopeName, scopeNode, 'propagated function call return sub-property equivalency');
-            // Ensure the database entry has the usage path
-            this.addUsageToEquivalencyDatabaseEntry(newPath, newEquivalentValue, equivalentScopeName, scopeNode.name);
+            for (const subValue of subValues) {
+                if (typeof subValue !== 'string')
+                    continue;
+                // Convert alias/reduceSource paths to returnValue paths
+                let effectiveSubPath = subPath;
+                if (isAliasSub && !isReturnValueSub) {
+                    // Replace the alias prefix with returnValue
+                    effectiveSubPath =
+                        'returnValue' + subPath.substring(returnValueAlias.length);
+                }
+                else if (isReduceSourceSub && !isReturnValueSub && !isAliasSub) {
+                    // Replace the reduce source prefix with returnValue
+                    effectiveSubPath =
+                        'returnValue' + subPath.substring(reduceSourceVar.length);
+                }
+                const subPropertyPath = effectiveSubPath.substring('returnValue'.length);
+                const newPath = cleanPath(path + subPropertyPath, allPaths);
+                let newEquivalentValue = cleanPath(subValue.replace(/::cyDuplicateKey\d+::/g, ''), allPaths);
+                // Resolve variable references through parent scope equivalencies
+                const resolved = this.resolveVariableThroughParentScopes(newEquivalentValue, callbackScope, allPaths);
+                newEquivalentValue = resolved.resolvedPath;
+                const equivalentScopeName = resolved.scopeName;
+                if (!newEquivalentValue || !this.isValidPath(newEquivalentValue))
+                    continue;
+                this.addEquivalency(newPath, newEquivalentValue, equivalentScopeName, scopeNode, 'propagated function call return sub-property equivalency');
+                // Ensure the database entry has the usage path
+                this.addUsageToEquivalencyDatabaseEntry(newPath, newEquivalentValue, equivalentScopeName, scopeNode.name);
+            }
         }
     }
     /**
@@ -1476,7 +1583,14 @@ export class ScopeDataStructure {
             const parentScope = this.scopeNodes[parentScopeName];
             if (!parentScope?.analysis?.isolatedEquivalentVariables)
                 continue;
-            const rootEquiv = parentScope.analysis.isolatedEquivalentVariables[rootVar];
+            const rawRootEquiv = parentScope.analysis.isolatedEquivalentVariables[rootVar];
+            // Normalize to array and use first string value
+            const rootEquivs = Array.isArray(rawRootEquiv)
+                ? rawRootEquiv
+                : rawRootEquiv
+                    ? [rawRootEquiv]
+                    : [];
+            const rootEquiv = rootEquivs.find((r) => typeof r === 'string');
             if (typeof rootEquiv === 'string') {
                 return {
                     resolvedPath: cleanPath(rootEquiv + restOfPath, allPaths),
@@ -1670,6 +1784,7 @@ export class ScopeDataStructure {
             const remainingPath = this.joinPathParts(remainingPathParts);
             if (relevantSubPathParts.every((part, i) => part === schemaPathParts[i]) &&
                 equivalentValue.scopeNodeName === scopeNode.name) {
+                // DEBUG
                 continue;
             }
             const newEquivalentPath = this.joinPathParts([schemaPath, remainingPath]);
@@ -1811,6 +1926,8 @@ export class ScopeDataStructure {
                         return;
                     }
                     const usageScopeNode = this.getScopeOrFunctionCallInfo(usageEquivalency.scopeNodeName);
+                    if (!usageScopeNode)
+                        continue;
                     // Guard against infinite recursion by tracking which paths we've already
                     // added from addComplexSourcePathVariables
                     if (this.visitedTracker.checkAndMarkComplexSourceVisited(usageScopeNode.name, newUsageEquivalentPath)) {
@@ -1859,6 +1976,8 @@ export class ScopeDataStructure {
                         continue;
                     }
                     const usageScopeNode = this.getScopeOrFunctionCallInfo(usageEquivalency.scopeNodeName);
+                    if (!usageScopeNode)
+                        continue;
                     // This is put in place to avoid propagating array functions like 'filter' through complex equivalencies
                     // but may cause problems if the funtion call is not on a known object (e.g. string or array)
                     if (newUsageEquivalentPath.endsWith(')') ||
@@ -1955,9 +2074,70 @@ export class ScopeDataStructure {
             // Update inverted index
             this.intermediatesOrderIndex.set(pathId, databaseEntry);
             if (intermediateIndex === 0) {
-                const isValidSourceCandidate = pathInfo.schemaPath.startsWith('signature[') ||
+                let isValidSourceCandidate = pathInfo.schemaPath.startsWith('signature[') ||
                     pathInfo.schemaPath.includes('functionCallReturnValue');
-                if (isValidSourceCandidate) {
+                // Check if path STARTS with a spread pattern like [...var]
+                // This handles cases like [...files][][0] or [...files].sort(...).functionCallReturnValue[][0]
+                // where the spread source variable needs to be resolved to a signature path.
+                // We do this REGARDLESS of isValidSourceCandidate because even paths containing
+                // functionCallReturnValue may need spread resolution to trace back to the signature.
+                const spreadMatch = pathInfo.schemaPath.match(/^\[\.\.\.(\w+)\]/);
+                if (spreadMatch) {
+                    const spreadVar = spreadMatch[1];
+                    const spreadPattern = spreadMatch[0]; // The full [...var] match
+                    const scopeNode = this.scopeNodes[pathInfo.scopeNodeName];
+                    if (scopeNode?.equivalencies) {
+                        // Follow the equivalency chain to find a signature path
+                        // e.g., files (cyScope1) → files (root) → signature[0].files
+                        const resolveToSignature = (varName, currentScopeName, visited) => {
+                            const visitKey = `${currentScopeName}::${varName}`;
+                            if (visited.has(visitKey))
+                                return null;
+                            visited.add(visitKey);
+                            const currentScope = this.scopeNodes[currentScopeName];
+                            if (!currentScope?.equivalencies)
+                                return null;
+                            const varEquivs = currentScope.equivalencies[varName];
+                            if (!varEquivs)
+                                return null;
+                            // First check if any equivalency directly points to a signature path
+                            const signatureEquiv = varEquivs.find((eq) => eq.schemaPath.startsWith('signature['));
+                            if (signatureEquiv) {
+                                return signatureEquiv;
+                            }
+                            // Otherwise, follow the chain to other scopes
+                            for (const equiv of varEquivs) {
+                                // If the equivalency points to the same variable in a different scope,
+                                // follow the chain
+                                if (equiv.schemaPath === varName &&
+                                    equiv.scopeNodeName !== currentScopeName) {
+                                    const result = resolveToSignature(varName, equiv.scopeNodeName, visited);
+                                    if (result)
+                                        return result;
+                                }
+                            }
+                            return null;
+                        };
+                        const signatureEquiv = resolveToSignature(spreadVar, pathInfo.scopeNodeName, new Set());
+                        if (signatureEquiv) {
+                            // Replace ONLY the [...var] part with the resolved signature path
+                            // This preserves any suffix like .sort(...).functionCallReturnValue[][0]
+                            const resolvedPath = pathInfo.schemaPath.replace(spreadPattern, signatureEquiv.schemaPath);
+                            // Add the resolved path as a source candidate
+                            if (!databaseEntry.sourceCandidates.some((sc) => sc.schemaPath === resolvedPath &&
+                                sc.scopeNodeName === pathInfo.scopeNodeName)) {
+                                databaseEntry.sourceCandidates.push({
+                                    scopeNodeName: pathInfo.scopeNodeName,
+                                    schemaPath: resolvedPath,
+                                });
+                            }
+                            isValidSourceCandidate = true;
+                        }
+                    }
+                }
+                if (isValidSourceCandidate &&
+                    !databaseEntry.sourceCandidates.some((sc) => sc.schemaPath === pathInfo.schemaPath &&
+                        sc.scopeNodeName === pathInfo.scopeNodeName)) {
                     databaseEntry.sourceCandidates.push(pathInfo);
                 }
             }
@@ -2103,6 +2283,13 @@ export class ScopeDataStructure {
                 delete scopeNode.schema[key];
             }
         }
+        // Ensure parameter-to-signature equivalencies are fully propagated.
+        // When a parameter variable (e.g., `node`) is equivalenced to `signature[N]`,
+        // all sub-paths of that variable should also appear under `signature[N]`.
+        // This handles cases where the sub-path was added to the schema via a propagation
+        // chain that already included the variable↔signature equivalency, causing the
+        // cycle detection to prevent the reverse mapping.
+        this.propagateParameterToSignaturePaths(scopeNode);
         fillInSchemaGapsAndUnknowns(scopeNode, fillInUnknowns);
         if (final) {
             for (const manager of this.equivalencyManagers) {
@@ -2114,6 +2301,40 @@ export class ScopeDataStructure {
             ensureSchemaConsistency(scopeNode.schema);
         }
     }
+    /**
+     * For each equivalency where a simple variable maps to signature[N],
+     * ensure all sub-paths of that variable are reflected under signature[N].
+     */
+    propagateParameterToSignaturePaths(scopeNode) {
+        // Find variable → signature[N] equivalencies
+        for (const [varName, equivalencies] of Object.entries(scopeNode.equivalencies)) {
+            // Only process simple variable names (no dots, brackets, or parens)
+            if (varName.includes('.') ||
+                varName.includes('[') ||
+                varName.includes('(')) {
+                continue;
+            }
+            for (const equiv of equivalencies) {
+                if (equiv.scopeNodeName === scopeNode.name &&
+                    equiv.schemaPath.startsWith('signature[')) {
+                    const signaturePath = equiv.schemaPath;
+                    const varPrefix = varName + '.';
+                    const varBracketPrefix = varName + '[';
+                    // Find all schema keys starting with the variable
+                    for (const key in scopeNode.schema) {
+                        if (key.startsWith(varPrefix) || key.startsWith(varBracketPrefix)) {
+                            const suffix = key.slice(varName.length);
+                            const sigKey = signaturePath + suffix;
+                            // Only add if the signature path doesn't already exist
+                            if (!scopeNode.schema[sigKey]) {
+                                scopeNode.schema[sigKey] = scopeNode.schema[key];
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
     filterAndConvertSchema({ filterPath, newPath, schema, }) {
         const filterPathParts = this.splitPath(filterPath);
         return Object.keys(schema).reduce((acc, key) => {
@@ -2173,6 +2394,10 @@ export class ScopeDataStructure {
                             path,
                             ...this.splitPath(key).slice(equivalentValueSchemaPathParts.length),
                         ]);
+                        // PERF: Skip keys with repeated function-call signature patterns
+                        // to prevent recursive type expansion (e.g., string.localeCompare returns string)
+                        if (this.hasExcessivePatternRepetition(newKey))
+                            continue;
                         resolvedSchema[newKey] = value;
                     }
                 }
@@ -2194,6 +2419,9 @@ export class ScopeDataStructure {
                 if (!subSchema)
                     continue;
                 for (const resolvedKey in subSchema) {
+                    // PERF: Skip keys with repeated function-call signature patterns
+                    if (this.hasExcessivePatternRepetition(resolvedKey))
+                        continue;
                     if (!resolvedSchema[resolvedKey] ||
                         subSchema[resolvedKey] === 'unknown') {
                         resolvedSchema[resolvedKey] = subSchema[resolvedKey];
@@ -2367,18 +2595,204 @@ export class ScopeDataStructure {
         if (!scopeNode) {
             return {};
         }
-        const entries = this.equivalencyDatabase.filter((entry) => entry.usages.some((usage) => usage.scopeNodeName === scopeNode.name));
-        return entries.reduce((acc, entry) => {
+        // Collect all descendant scope names (including the scope itself)
+        // This ensures we include external calls from nested scopes like cyScope2
+        const getAllDescendantScopeNames = (node) => {
+            const names = new Set([node.name]);
+            for (const child of node.children) {
+                for (const name of getAllDescendantScopeNames(child)) {
+                    names.add(name);
+                }
+            }
+            return names;
+        };
+        const treeNode = this.scopeTreeManager.findNode(scopeNode.name);
+        const descendantScopeNames = treeNode
+            ? getAllDescendantScopeNames(treeNode)
+            : new Set([scopeNode.name]);
+        // Get all external function calls made from this scope or any descendant scope
+        // This allows us to include prop equivalencies from JSX components
+        // that were rendered in nested scopes (e.g., FileTableRow called from cyScope2)
+        const externalCallsFromScope = this.externalFunctionCalls.filter((efc) => descendantScopeNames.has(efc.callScope));
+        const externalCallNames = new Set(externalCallsFromScope.map((efc) => efc.name));
+        // Helper to check if a usage belongs to this scope (directly, via descendant, or via external call)
+        const usageMatchesScope = (usage) => descendantScopeNames.has(usage.scopeNodeName) ||
+            externalCallNames.has(usage.scopeNodeName);
+        const entries = this.equivalencyDatabase.filter((entry) => entry.usages.some(usageMatchesScope));
+        // Helper to resolve a source candidate through equivalency chains to find signature paths
+        const resolveToSignature = (source, visited) => {
+            const visitKey = `${source.scopeNodeName}::${source.schemaPath}`;
+            if (visited.has(visitKey))
+                return [];
+            visited.add(visitKey);
+            // If already a signature path, return as-is
+            if (source.schemaPath.startsWith('signature[')) {
+                return [source];
+            }
+            const currentScope = this.scopeNodes[source.scopeNodeName];
+            if (!currentScope?.equivalencies)
+                return [source];
+            // Check for direct equivalencies FIRST (full path match)
+            // This ensures paths like "useMemo(...).functionCallReturnValue" follow to "cyScope1::returnValue"
+            // before prefix matching tries "useMemo(...)" which goes to the useMemo scope
+            const directEquivs = currentScope.equivalencies[source.schemaPath];
+            if (directEquivs?.length > 0) {
+                const results = [];
+                for (const equiv of directEquivs) {
+                    const resolved = resolveToSignature({
+                        scopeNodeName: equiv.scopeNodeName,
+                        schemaPath: equiv.schemaPath,
+                    }, visited);
+                    results.push(...resolved);
+                }
+                if (results.length > 0)
+                    return results;
+            }
+            // Handle spread patterns like [...items].sort().functionCallReturnValue
+            // Extract the spread variable and resolve it through the equivalency chain
+            const spreadMatch = source.schemaPath.match(/^\[\.\.\.(\w+)\]/);
+            if (spreadMatch) {
+                const spreadVar = spreadMatch[1];
+                const spreadPattern = spreadMatch[0];
+                const varEquivs = currentScope.equivalencies[spreadVar];
+                if (varEquivs?.length > 0) {
+                    const results = [];
+                    for (const equiv of varEquivs) {
+                        // Follow the variable equivalency and then resolve from there
+                        const resolvedVar = resolveToSignature({
+                            scopeNodeName: equiv.scopeNodeName,
+                            schemaPath: equiv.schemaPath,
+                        }, visited);
+                        // For each resolved variable path, create the full path with array element suffix
+                        for (const rv of resolvedVar) {
+                            if (rv.schemaPath.startsWith('signature[')) {
+                                // Get the suffix after the spread pattern
+                                let suffix = source.schemaPath.slice(spreadPattern.length);
+                                // Clean the suffix: strip array method chains like .sort(...).functionCallReturnValue[]
+                                // These don't change the data identity, just transform it.
+                                // Keep only the final element access parts like [0], [1], etc.
+                                // Pattern: strip everything from a method call up through functionCallReturnValue[]
+                                suffix = suffix.replace(/\.\w+\([^)]*\)\.functionCallReturnValue\[\]/g, '');
+                                // Also handle simpler case without nested parens
+                                suffix = suffix.replace(/\.sort\(\w*\(\)\)\.functionCallReturnValue\[\]/g, '');
+                                // Add [] to indicate array element access from the spread
+                                const resolvedPath = rv.schemaPath + '[]' + suffix;
+                                results.push({
+                                    scopeNodeName: rv.scopeNodeName,
+                                    schemaPath: resolvedPath,
+                                });
+                            }
+                        }
+                    }
+                    if (results.length > 0)
+                        return results;
+                }
+            }
+            // Try to find prefix equivalencies that can resolve this path
+            // For path like "cyScope3().signature[0][0]", check "cyScope3().signature[0]", etc.
+            const pathParts = this.splitPath(source.schemaPath);
+            for (let i = pathParts.length - 1; i > 0; i--) {
+                const prefix = this.joinPathParts(pathParts.slice(0, i));
+                const suffix = this.joinPathParts(pathParts.slice(i));
+                const prefixEquivs = currentScope.equivalencies[prefix];
+                if (prefixEquivs?.length > 0) {
+                    const results = [];
+                    for (const equiv of prefixEquivs) {
+                        const newPath = this.joinPathParts([equiv.schemaPath, suffix]);
+                        const resolved = resolveToSignature({ scopeNodeName: equiv.scopeNodeName, schemaPath: newPath }, visited);
+                        results.push(...resolved);
+                    }
+                    if (results.length > 0)
+                        return results;
+                }
+            }
+            return [source];
+        };
+        const acc = entries.reduce((result, entry) => {
             var _a;
             if (entry.sourceCandidates.length === 0)
-                return acc;
-            const usages = entry.usages.filter((u) => u.scopeNodeName === scopeNode.name);
+                return result;
+            const usages = entry.usages.filter(usageMatchesScope);
             for (const usage of usages) {
-                acc[_a = usage.schemaPath] || (acc[_a] = []);
-                acc[usage.schemaPath].push(...entry.sourceCandidates);
+                result[_a = usage.schemaPath] || (result[_a] = []);
+                // Resolve each source candidate through the equivalency chain
+                for (const source of entry.sourceCandidates) {
+                    const resolvedSources = resolveToSignature(source, new Set());
+                    result[usage.schemaPath].push(...resolvedSources);
+                }
             }
-            return acc;
+            return result;
         }, {});
+        // Post-processing: enrich useState-backed sources with co-located external
+        // function calls. When a useState value resolves to a setter variable that
+        // lives in the same scope as a fetch/API call, that fetch is a data source.
+        this.enrichUseStateSourcesWithCoLocatedCalls(acc);
+        return acc;
+    }
+    /**
+     * For each source that ends at a useState path, check if the setter was called
+     * from a scope that also contains external function calls (like fetch).
+     * If so, add those external calls as additional source candidates.
+     */
+    enrichUseStateSourcesWithCoLocatedCalls(acc) {
+        const rootScopeName = this.scopeTreeManager.getRootName();
+        const rootScope = this.scopeNodes[rootScopeName];
+        if (!rootScope)
+            return;
+        // Collect all descendants for each scope node
+        const getAllDescendants = (node) => {
+            const names = new Set([node.name]);
+            for (const child of node.children) {
+                for (const name of getAllDescendants(child)) {
+                    names.add(name);
+                }
+            }
+            return names;
+        };
+        for (const [usagePath, sources] of Object.entries(acc)) {
+            const additionalSources = [];
+            for (const source of sources) {
+                // Check if this source is a useState-related terminal path
+                // (e.g., useState(X).functionCallReturnValue[1] or useState(X).signature[0])
+                if (!source.schemaPath.match(/^useState\([^)]*\)\./))
+                    continue;
+                // Find the useState call from the source path
+                const useStateCallMatch = source.schemaPath.match(/^(useState\([^)]*\))\./);
+                if (!useStateCallMatch)
+                    continue;
+                const useStateCall = useStateCallMatch[1];
+                // Look in the root scope for the useState value equivalency
+                // which tells us where the setter was called from
+                const valuePath = `${useStateCall}.functionCallReturnValue[0]`;
+                const valueEquivs = rootScope.equivalencies[valuePath];
+                if (!valueEquivs)
+                    continue;
+                for (const equiv of valueEquivs) {
+                    // Find the scope where the setter was called
+                    const setterScopeName = equiv.scopeNodeName;
+                    const setterScopeTree = this.scopeTreeManager.findNode(setterScopeName);
+                    if (!setterScopeTree)
+                        continue;
+                    // Get all descendant scope names from the setter scope
+                    const relatedScopes = getAllDescendants(setterScopeTree);
+                    // Find external function calls in those scopes whose return values
+                    // are actually consumed (assigned to a variable). This excludes
+                    // fire-and-forget calls like analytics.track() or console.log().
+                    const coLocatedCalls = this.externalFunctionCalls.filter((efc) => relatedScopes.has(efc.callScope) &&
+                        efc.receivingVariableNames &&
+                        efc.receivingVariableNames.length > 0);
+                    for (const call of coLocatedCalls) {
+                        additionalSources.push({
+                            scopeNodeName: call.callScope,
+                            schemaPath: `${call.callSignature}.functionCallReturnValue`,
+                        });
+                    }
+                }
+            }
+            if (additionalSources.length > 0) {
+                acc[usagePath].push(...additionalSources);
+            }
+        }
     }
     getUsageEquivalencies(functionName) {
         const scopeNode = this.getScopeOrFunctionCallInfo(functionName);
@@ -2443,6 +2857,49 @@ export class ScopeDataStructure {
                 }
             }
         }
+        // Enrich schema with deeply nested paths from internal function call scopes.
+        // When a function call like traverse(tree) exists, and traverse's scope has
+        // signature[0].children[path][entityName] (from propagateParameterToSignaturePaths),
+        // we need to map those paths back to the argument variable (tree) in this scope.
+        // This handles cases where cycle detection prevented the equivalency chain from
+        // propagating deep paths during Phase 2 batch queue processing.
+        for (const equivalenceKey in equivalencies ?? {}) {
+            // Look for keys matching function call pattern: funcName(...).signature[N]
+            const funcCallMatch = equivalenceKey.match(/^([^(]+)\(.*?\)\.(signature\[\d+\])$/);
+            if (!funcCallMatch)
+                continue;
+            const calledFunctionName = funcCallMatch[1];
+            const signatureParam = funcCallMatch[2]; // e.g., "signature[0]"
+            for (const equivalenceValue of equivalencies[equivalenceKey]) {
+                if (equivalenceValue.scopeNodeName !== scopeName)
+                    continue;
+                const targetVariable = equivalenceValue.schemaPath;
+                // Get the called function's schema (includes propagated parameter paths)
+                const childSchema = this.getSchema({
+                    scopeName: calledFunctionName,
+                });
+                if (!childSchema)
+                    continue;
+                // Map child function's signature paths to parent variable paths
+                const sigPrefix = signatureParam + '.';
+                const sigBracketPrefix = signatureParam + '[';
+                for (const childKey in childSchema) {
+                    let suffix = null;
+                    if (childKey.startsWith(sigPrefix)) {
+                        suffix = childKey.slice(signatureParam.length);
+                    }
+                    else if (childKey.startsWith(sigBracketPrefix)) {
+                        suffix = childKey.slice(signatureParam.length);
+                    }
+                    if (suffix !== null) {
+                        const parentKey = targetVariable + suffix;
+                        if (!schema[parentKey]) {
+                            schema[parentKey] = childSchema[childKey];
+                        }
+                    }
+                }
+            }
+        }
         // Propagate nested paths from variables to their signature equivalents
         // e.g., if workouts = signature[0].workouts, then workouts[].title becomes
         // signature[0].workouts[].title
@@ -2664,13 +3121,35 @@ export class ScopeDataStructure {
     getEquivalentSignatureVariables() {
         const scopeNode = this.scopeNodes[this.scopeTreeManager.getRootName()];
         const equivalentSignatureVariables = {};
+        // Helper to add equivalencies - accumulates into array if multiple values for same key
+        // This is critical for OR expressions like `x = a || b` where x should map to both a and b
+        const addEquivalency = (key, value) => {
+            const existing = equivalentSignatureVariables[key];
+            if (existing === undefined) {
+                // First value - store as string
+                equivalentSignatureVariables[key] = value;
+            }
+            else if (typeof existing === 'string') {
+                if (existing !== value) {
+                    // Second different value - convert to array
+                    equivalentSignatureVariables[key] = [existing, value];
+                }
+                // Same value - no change needed
+            }
+            else {
+                // Already an array - add if not already present
+                if (!existing.includes(value)) {
+                    existing.push(value);
+                }
+            }
+        };
         for (const [path, equivalentValues] of Object.entries(scopeNode.equivalencies)) {
             for (const equivalentValue of equivalentValues) {
                 // Case 1: Props/signature equivalencies (existing behavior)
                 // Maps local variable names to their signature paths
                 // e.g., "propValue" -> "signature[0].prop"
                 if (path.startsWith('signature[')) {
-                    equivalentSignatureVariables[equivalentValue.schemaPath] = path;
+                    addEquivalency(equivalentValue.schemaPath, path);
                 }
                 // Case 2: Hook variable equivalencies (new behavior)
                 // The equivalencies are stored as: path = variable name, schemaPath = data source
@@ -2698,7 +3177,7 @@ export class ScopeDataStructure {
                                 hookCallPath = dbEntry.sourceCandidates[0].schemaPath;
                             }
                         }
-                        equivalentSignatureVariables[path] = hookCallPath;
+                        addEquivalency(path, hookCallPath);
                     }
                 }
                 // Case 3: Destructured variables from local variables
@@ -2710,10 +3189,15 @@ export class ScopeDataStructure {
                     !equivalentValue.schemaPath.startsWith('signature[') && // not a signature path
                     !equivalentValue.schemaPath.endsWith('.functionCallReturnValue') // not already handled above
                 ) {
-                    // Only add if we haven't already captured this variable in Case 1 or 2
-                    if (!(path in equivalentSignatureVariables)) {
-                        equivalentSignatureVariables[path] = equivalentValue.schemaPath;
+                    // Skip bare "returnValue" from child scopes — this is the child's return value,
+                    // not a meaningful data source path in the parent scope
+                    if (equivalentValue.schemaPath === 'returnValue' &&
+                        equivalentValue.scopeNodeName !==
+                            this.scopeTreeManager.getRootName()) {
+                        continue;
                     }
+                    // Add equivalency (will accumulate if multiple values for OR expressions)
+                    addEquivalency(path, equivalentValue.schemaPath);
                 }
                 // Case 4: Child component prop mappings (Fix 22)
                 // When parent renders <ChildComponent prop={value} />, we get equivalencies like:
@@ -2724,7 +3208,7 @@ export class ScopeDataStructure {
                 if (path.includes('().signature[') &&
                     !equivalentValue.schemaPath.includes('()') // schemaPath is a simple variable, not a function call
                 ) {
-                    equivalentSignatureVariables[path] = equivalentValue.schemaPath;
+                    addEquivalency(path, equivalentValue.schemaPath);
                 }
                 // Case 5: Destructured function parameters (Fix 25)
                 // When a function has destructured props: function Comp({ propA, propB }: Props)
@@ -2737,7 +3221,7 @@ export class ScopeDataStructure {
                 if (!path.includes('.') && // path is a simple identifier (destructured prop name)
                     equivalentValue.schemaPath.startsWith('signature[') // schemaPath IS a signature path
                 ) {
-                    equivalentSignatureVariables[path] = equivalentValue.schemaPath;
+                    addEquivalency(path, equivalentValue.schemaPath);
                 }
                 // Case 7: Method calls on variables that result in .functionCallReturnValue (Fix 33)
                 // When we have patterns like:
@@ -2749,8 +3233,7 @@ export class ScopeDataStructure {
                 // segments -> useParams().functionCallReturnValue['*'].split('/').functionCallReturnValue
                 if (!path.includes('.') && // path is a simple identifier
                     equivalentValue.schemaPath.endsWith('.functionCallReturnValue') && // ends with function return
-                    equivalentValue.schemaPath.includes('.') && // has property access (method call)
-                    !(path in equivalentSignatureVariables) // not already captured
+                    equivalentValue.schemaPath.includes('.') // has property access (method call)
                 ) {
                     // Check if this looks like a method call on a variable (not a hook call)
                     // Hook calls look like: hookName() or hookName<T>()
@@ -2761,7 +3244,7 @@ export class ScopeDataStructure {
                     const parenPos = hookCallPath.indexOf('(');
                     if (dotBeforeParen !== -1 && dotBeforeParen < parenPos) {
                         // This is a method call like "splat.split('/')", not a hook call
-                        equivalentSignatureVariables[path] = equivalentValue.schemaPath;
+                        addEquivalency(path, equivalentValue.schemaPath);
                     }
                 }
             }
@@ -2788,8 +3271,9 @@ export class ScopeDataStructure {
                         !equivalentValue.schemaPath.includes('()') // schemaPath is a simple variable
                     ) {
                         // Only add if not already present from the root scope
+                        // Root scope values take precedence over child scope values
                         if (!(path in equivalentSignatureVariables)) {
-                            equivalentSignatureVariables[path] = equivalentValue.schemaPath;
+                            addEquivalency(path, equivalentValue.schemaPath);
                         }
                     }
                 }
@@ -2799,9 +3283,72 @@ export class ScopeDataStructure {
         // E.g., analysis → currentEntityAnalysis → useLoaderData().functionCallReturnValue.currentEntityAnalysis
         // We need multiple passes because resolutions can depend on each other
         const maxIterations = 5; // Prevent infinite loops
+        // Helper function to resolve a single source path using equivalencies
+        const resolveSourcePath = (sourcePath, equivMap) => {
+            // Extract base variable from the path
+            const dotIndex = sourcePath.indexOf('.');
+            const bracketIndex = sourcePath.indexOf('[');
+            let baseVar;
+            let rest;
+            if (dotIndex === -1 && bracketIndex === -1) {
+                baseVar = sourcePath;
+                rest = '';
+            }
+            else if (dotIndex === -1) {
+                baseVar = sourcePath.slice(0, bracketIndex);
+                rest = sourcePath.slice(bracketIndex);
+            }
+            else if (bracketIndex === -1) {
+                baseVar = sourcePath.slice(0, dotIndex);
+                rest = sourcePath.slice(dotIndex);
+            }
+            else {
+                const firstIndex = Math.min(dotIndex, bracketIndex);
+                baseVar = sourcePath.slice(0, firstIndex);
+                rest = sourcePath.slice(firstIndex);
+            }
+            // Look up the base variable in equivalencies
+            if (baseVar in equivMap && equivMap[baseVar] !== sourcePath) {
+                const baseResolved = equivMap[baseVar];
+                // Skip if baseResolved is an array (handle later)
+                if (Array.isArray(baseResolved))
+                    return null;
+                // If it resolves to a signature path, build the full resolved path
+                if (baseResolved.startsWith('signature[') ||
+                    baseResolved.includes('()')) {
+                    if (baseResolved.endsWith('()')) {
+                        return baseResolved + '.functionCallReturnValue' + rest;
+                    }
+                    return baseResolved + rest;
+                }
+            }
+            return null;
+        };
         for (let iteration = 0; iteration < maxIterations; iteration++) {
             let changed = false;
-            for (const [varName, sourcePath] of Object.entries(equivalentSignatureVariables)) {
+            for (const [varName, sourcePathOrArray] of Object.entries(equivalentSignatureVariables)) {
+                // Handle arrays (OR expressions) by resolving each element
+                if (Array.isArray(sourcePathOrArray)) {
+                    const resolvedArray = [];
+                    let arrayChanged = false;
+                    for (const sourcePath of sourcePathOrArray) {
+                        // Try to resolve this path using transitive resolution
+                        const resolved = resolveSourcePath(sourcePath, equivalentSignatureVariables);
+                        if (resolved && resolved !== sourcePath) {
+                            resolvedArray.push(resolved);
+                            arrayChanged = true;
+                        }
+                        else {
+                            resolvedArray.push(sourcePath);
+                        }
+                    }
+                    if (arrayChanged) {
+                        equivalentSignatureVariables[varName] = resolvedArray;
+                        changed = true;
+                    }
+                    continue;
+                }
+                const sourcePath = sourcePathOrArray;
                 // Skip if already fully resolved (contains function call syntax)
                 // BUT first check for computed value patterns that need resolution (Fix 28)
                 // AND method call patterns that need base variable resolution (Fix 33)
@@ -2854,6 +3401,9 @@ export class ScopeDataStructure {
                         if (baseVar in equivalentSignatureVariables &&
                             baseVar !== varName) {
                             const baseResolved = equivalentSignatureVariables[baseVar];
+                            // Skip if baseResolved is an array (OR expression)
+                            if (Array.isArray(baseResolved))
+                                continue;
                             // Only resolve if the base resolved to something useful (contains () or .)
                             if (baseResolved.includes('()') || baseResolved.includes('.')) {
                                 const newPath = baseResolved + rest;
@@ -2909,7 +3459,13 @@ export class ScopeDataStructure {
                     rest = '';
                 }
                 if (baseVar in equivalentSignatureVariables && baseVar !== varName) {
-                    const baseResolved = equivalentSignatureVariables[baseVar];
+                    // Handle array case (OR expressions) - use first element
+                    const rawBaseResolved = equivalentSignatureVariables[baseVar];
+                    const baseResolved = Array.isArray(rawBaseResolved)
+                        ? rawBaseResolved[0]
+                        : rawBaseResolved;
+                    if (!baseResolved)
+                        continue;
                     // If the base resolves to a hook call, add .functionCallReturnValue
                     if (baseResolved.endsWith('()')) {
                         const newPath = baseResolved + '.functionCallReturnValue' + rest;
@@ -3199,6 +3755,7 @@ export class ScopeDataStructure {
      */
     getEnrichedConditionalUsages() {
         const enriched = {};
+        console.log(`[getEnrichedConditionalUsages] Processing ${Object.keys(this.rawConditionalUsages).length} conditional paths: [${Object.keys(this.rawConditionalUsages).join(', ')}]`);
         for (const [path, usages] of Object.entries(this.rawConditionalUsages)) {
             // Try to trace this path back to a data source
             // First, try the root scope
@@ -3206,9 +3763,47 @@ export class ScopeDataStructure {
             const explanation = this.explainPath(rootScopeName, path);
             let sourceDataPath;
             if (explanation.source) {
-                // Build the full data path: scopeName.path
-                sourceDataPath = `${explanation.source.scope}.${explanation.source.path}`;
+                const { scope, path: sourcePath } = explanation.source;
+                // Build initial path — avoid redundant prefix when path already contains the scope call
+                let fullPath;
+                if (sourcePath.startsWith(`${scope}(`)) {
+                    fullPath = sourcePath;
+                }
+                else {
+                    fullPath = `${scope}.${sourcePath}`;
+                }
+                sourceDataPath = fullPath;
+                console.log(`[getEnrichedConditionalUsages] "${path}" explainPath → scope="${scope}", sourcePath="${sourcePath}" → sourceDataPath="${sourceDataPath}"`);
+            }
+            else {
+                console.log(`[getEnrichedConditionalUsages] "${path}" explainPath → no source found`);
+            }
+            // If explainPath didn't find a useful external source (e.g., it traced to
+            // useState or just to the component scope itself), check sourceEquivalencies
+            // for an external function call source like a fetch call
+            const hasExternalSource = sourceDataPath?.includes('.functionCallReturnValue');
+            if (!hasExternalSource) {
+                console.log(`[getEnrichedConditionalUsages] "${path}" no external source (sourceDataPath="${sourceDataPath}"), checking sourceEquivalencies fallback...`);
+                const sourceEquiv = this.getSourceEquivalencies();
+                const returnValueKey = `returnValue.${path}`;
+                const sources = sourceEquiv[returnValueKey];
+                if (sources) {
+                    console.log(`[getEnrichedConditionalUsages] "${path}" sourceEquivalencies["${returnValueKey}"] has ${sources.length} sources: [${sources.map((s) => s.schemaPath).join(', ')}]`);
+                    const externalSource = sources.find((s) => s.schemaPath.includes('.functionCallReturnValue') &&
+                        !s.schemaPath.startsWith('useState('));
+                    if (externalSource) {
+                        console.log(`[getEnrichedConditionalUsages] "${path}" sourceEquivalencies fallback found external source: "${externalSource.schemaPath}"`);
+                        sourceDataPath = externalSource.schemaPath;
+                    }
+                    else {
+                        console.log(`[getEnrichedConditionalUsages] "${path}" sourceEquivalencies fallback found no external function call source`);
+                    }
+                }
+                else {
+                    console.log(`[getEnrichedConditionalUsages] "${path}" sourceEquivalencies["${returnValueKey}"] not found`);
+                }
             }
+            console.log(`[getEnrichedConditionalUsages] "${path}" FINAL sourceDataPath="${sourceDataPath ?? '(none)'}" (${usages.length} usages)`);
             enriched[path] = usages.map((usage) => ({
                 ...usage,
                 sourceDataPath,
@@ -3467,11 +4062,21 @@ export class ScopeDataStructure {
                     perVariableSchemas = undefined;
                 }
             }
+            // Enrich the schema with inferred types by applying fillInSchemaGapsAndUnknowns.
+            // This ensures the serialized schema has the same type inference as getReturnValue().
+            // Without this, evidence like "entities[].analyses: array" becomes "unknown".
+            const enrichedSchema = { ...efc.schema };
+            const tempScopeNode = {
+                name: efc.name,
+                schema: enrichedSchema,
+                equivalencies: efc.equivalencies ?? {},
+            };
+            fillInSchemaGapsAndUnknowns(tempScopeNode, true);
             return {
                 name: efc.name,
                 callSignature: efc.callSignature,
                 callScope: efc.callScope,
-                schema: efc.schema,
+                schema: enrichedSchema,
                 equivalencies: efc.equivalencies
                     ? Object.entries(efc.equivalencies).reduce((acc, [key, vars]) => {
                         // Clean cyScope from the key as well as variable properties