@codeyam/codeyam-cli 0.1.0-staging.323686 → 0.1.0-staging.4813bf3

package/analyzer-template/packages/ai/src/lib/dataStructure/ScopeDataStructure.ts

@@ -152,7 +152,7 @@ export interface ScopeInfo {
     [childComponentName: string]: Array<{
       path: string;
       conditionType: 'truthiness' | 'comparison';
-      location: 'if' | 'ternary' | 'logical-and' | 'switch';
+      location: 'if' | 'ternary' | 'logical-and' | 'switch' | 'unconditional';
       isNegated?: boolean;
     }>;
   };
@@ -397,6 +397,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 {
@@ -424,7 +425,7 @@ export class ScopeDataStructure {
       path: string;
       conditionType: 'truthiness' | 'comparison' | 'switch';
       comparedValues?: string[];
-      location: 'if' | 'ternary' | 'logical-and' | 'switch';
+      location: 'if' | 'ternary' | 'logical-and' | 'switch' | 'unconditional';
     }>
   > = {};
 
@@ -799,6 +800,11 @@ 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 =
@@ -1486,6 +1492,15 @@ export class ScopeDataStructure {
 
           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;
         } else if (
@@ -1499,6 +1514,11 @@ export class ScopeDataStructure {
             ...remainingSchemaPathParts,
           ]);
 
+          // PERF: Skip paths with repeated function-call signature patterns
+          if (this.hasExcessivePatternRepetition(newEquivalentPath)) {
+            continue;
+          }
+
           equivalentScopeNode.schema[newEquivalentPath] =
             scopeNode.schema[schemaPath];
         }
@@ -1618,6 +1638,23 @@ export class ScopeDataStructure {
       }
     }
 
+    // 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<string>();
+      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) {
@@ -1650,17 +1687,26 @@ export class ScopeDataStructure {
   private setInstantiatedVariables(scopeNode: ScopeNode) {
     let instantiatedVariables = scopeNode.analysis?.instantiatedVariables ?? [];
 
-    for (const [path, equivalentPath] of Object.entries(
+    for (const [path, rawEquivalentPath] of Object.entries(
       scopeNode.analysis.isolatedEquivalentVariables ?? {},
     )) {
-      if (typeof equivalentPath !== 'string') {
-        continue;
-      }
+      // 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);
+        if (equivalentPath.startsWith('signature[')) {
+          const equivalentPathParts = this.splitPath(equivalentPath);
+          instantiatedVariables.push(equivalentPathParts[0]);
+          instantiatedVariables.push(path);
+        }
       }
 
       const duplicateInstantiated = instantiatedVariables.find(
@@ -1673,9 +1719,14 @@ export class ScopeDataStructure {
       }
     }
 
-    instantiatedVariables = instantiatedVariables.filter(
-      (varName, index, self) => self.indexOf(varName) === index,
-    );
+    const instantiatedSeen = new Set<string>();
+    instantiatedVariables = instantiatedVariables.filter((varName) => {
+      if (instantiatedSeen.has(varName)) {
+        return false;
+      }
+      instantiatedSeen.add(varName);
+      return true;
+    });
 
     scopeNode.instantiatedVariables = instantiatedVariables;
 
@@ -1696,13 +1747,19 @@ export class ScopeDataStructure {
       ...parentScopeNode.instantiatedVariables.filter(
         (v) => !v.startsWith('signature[') && !v.startsWith('returnValue'),
       ),
-    ].filter(
-      (varName, index, self) =>
-        !instantiatedVariables.includes(varName) &&
-        self.indexOf(varName) === index,
-    );
+    ].filter((varName) => !instantiatedSeen.has(varName));
 
-    scopeNode.parentInstantiatedVariables = parentInstantiatedVariables;
+    const parentInstantiatedSeen = new Set<string>();
+    const dedupedParentInstantiatedVariables =
+      parentInstantiatedVariables.filter((varName) => {
+        if (parentInstantiatedSeen.has(varName)) {
+          return false;
+        }
+        parentInstantiatedSeen.add(varName);
+        return true;
+      });
+
+    scopeNode.parentInstantiatedVariables = dedupedParentInstantiatedVariables;
   }
 
   private trackFunctionCalls(scopeNode: ScopeNode) {
@@ -1718,172 +1775,198 @@ export class ScopeDataStructure {
     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',
-        );
+      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;
+          // 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;
+          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,
+          // 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 + '[',
                 );
-                const newPath = cleanPath(path + subPropertyPath, allPaths);
-                const newEquivalentValue = cleanPath(
-                  (subValue as string).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',
+                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
-              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
+                for (const subValue of subValues) {
+                  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,
-          );
+          // 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);
-        }
+            // 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);
+          // 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);
+          }
         }
       }
     }
@@ -2064,9 +2147,18 @@ export class ScopeDataStructure {
         const checkScope = this.scopeNodes[scopeName];
         if (!checkScope?.analysis?.isolatedEquivalentVariables) continue;
 
-        const functionRef =
+        const rawFunctionRef =
           checkScope.analysis.isolatedEquivalentVariables[functionName];
-        if (typeof functionRef === 'string' && functionRef.endsWith('F')) {
+        // 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;
         }
@@ -2094,19 +2186,24 @@ export class ScopeDataStructure {
 
     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
+      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: string | undefined;
-    if (typeof isolatedVars.returnValue === 'string') {
-      const reduceMatch = isolatedVars.returnValue.match(
+    if (typeof firstReturnValue === 'string') {
+      const reduceMatch = firstReturnValue.match(
         /^Object\.keys\((\w+)\)\.reduce\(.*\)\.functionCallReturnValue$/,
       );
       if (reduceMatch) {
@@ -2114,7 +2211,14 @@ export class ScopeDataStructure {
       }
     }
 
-    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.') ||
@@ -2132,57 +2236,59 @@ export class ScopeDataStructure {
         (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,
-      );
+      if (!isReturnValueSub && !isAliasSub && !isReduceSourceSub) continue;
+
+      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;
+        // 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;
+        if (!newEquivalentValue || !this.isValidPath(newEquivalentValue))
+          continue;
 
-      this.addEquivalency(
-        newPath,
-        newEquivalentValue,
-        equivalentScopeName,
-        scopeNode,
-        'propagated function call return sub-property equivalency',
-      );
+        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,
-      );
+        // Ensure the database entry has the usage path
+        this.addUsageToEquivalencyDatabaseEntry(
+          newPath,
+          newEquivalentValue,
+          equivalentScopeName,
+          scopeNode.name,
+        );
+      }
     }
   }
 
@@ -2222,8 +2328,15 @@ export class ScopeDataStructure {
       const parentScope = this.scopeNodes[parentScopeName];
       if (!parentScope?.analysis?.isolatedEquivalentVariables) continue;
 
-      const rootEquiv =
+      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),
@@ -2498,6 +2611,7 @@ export class ScopeDataStructure {
         relevantSubPathParts.every((part, i) => part === schemaPathParts[i]) &&
         equivalentValue.scopeNodeName === scopeNode.name
       ) {
+        // DEBUG
         continue;
       }
 
@@ -2684,6 +2798,8 @@ export class ScopeDataStructure {
             usageEquivalency.scopeNodeName,
           ) as ScopeNode;
 
+          if (!usageScopeNode) continue;
+
           // Guard against infinite recursion by tracking which paths we've already
           // added from addComplexSourcePathVariables
           if (
@@ -2763,6 +2879,8 @@ export class ScopeDataStructure {
             usageEquivalency.scopeNodeName,
           ) as ScopeNode;
 
+          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 (
@@ -2889,10 +3007,105 @@ export class ScopeDataStructure {
       this.intermediatesOrderIndex.set(pathId, databaseEntry);
 
       if (intermediateIndex === 0) {
-        const isValidSourceCandidate =
+        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: string,
+              currentScopeName: string,
+              visited: Set<string>,
+            ): { schemaPath: string; scopeNodeName: string } | null => {
+              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);
         }
       } else {
@@ -3120,6 +3333,14 @@ export class ScopeDataStructure {
       }
     }
 
+    // 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) {
@@ -3134,6 +3355,50 @@ export class ScopeDataStructure {
     }
   }
 
+  /**
+   * For each equivalency where a simple variable maps to signature[N],
+   * ensure all sub-paths of that variable are reflected under signature[N].
+   */
+  private propagateParameterToSignaturePaths(scopeNode: 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];
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
   private filterAndConvertSchema({
     filterPath,
     newPath,
@@ -3220,6 +3485,9 @@ export class ScopeDataStructure {
                 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;
           }
         }
@@ -3242,6 +3510,8 @@ 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'
@@ -3479,26 +3749,270 @@ export class ScopeDataStructure {
       return {};
     }
 
+    // Collect all descendant scope names (including the scope itself)
+    // This ensures we include external calls from nested scopes like cyScope2
+    const getAllDescendantScopeNames = (
+      node: import('./helpers/ScopeTreeManager').ScopeTreeNode,
+    ): Set<string> => {
+      const names = new Set<string>([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<string>([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: { scopeNodeName: string }) =>
+      descendantScopeNames.has(usage.scopeNodeName) ||
+      externalCallNames.has(usage.scopeNodeName);
+
     const entries = this.equivalencyDatabase.filter((entry) =>
-      entry.usages.some((usage) => usage.scopeNodeName === scopeNode.name),
+      entry.usages.some(usageMatchesScope),
     );
-    return entries.reduce(
-      (acc, entry) => {
-        if (entry.sourceCandidates.length === 0) return acc;
-        const usages = entry.usages.filter(
-          (u) => u.scopeNodeName === scopeNode.name,
-        );
+
+    // Helper to resolve a source candidate through equivalency chains to find signature paths
+    const resolveToSignature = (
+      source: Pick<ScopeVariable, 'scopeNodeName' | 'schemaPath'>,
+      visited: Set<string>,
+    ): Pick<ScopeVariable, 'scopeNodeName' | 'schemaPath'>[] => {
+      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: Pick<ScopeVariable, 'scopeNodeName' | 'schemaPath'>[] =
+          [];
+        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: Pick<ScopeVariable, 'scopeNodeName' | 'schemaPath'>[] =
+            [];
+          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: Pick<ScopeVariable, 'scopeNodeName' | 'schemaPath'>[] =
+            [];
+          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) => {
+        if (entry.sourceCandidates.length === 0) return result;
+        const usages = entry.usages.filter(usageMatchesScope);
         for (const usage of usages) {
-          acc[usage.schemaPath] ||= [];
-          acc[usage.schemaPath].push(...entry.sourceCandidates);
+          result[usage.schemaPath] ||= [];
+          // 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;
       },
       {} as Record<
         string,
         Pick<ScopeVariable, 'scopeNodeName' | 'schemaPath'>[]
       >,
     );
+
+    // 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.
+   */
+  private enrichUseStateSourcesWithCoLocatedCalls(
+    acc: Record<string, Pick<ScopeVariable, 'scopeNodeName' | 'schemaPath'>[]>,
+  ) {
+    const rootScopeName = this.scopeTreeManager.getRootName();
+    const rootScope = this.scopeNodes[rootScopeName];
+    if (!rootScope) return;
+
+    // Collect all descendants for each scope node
+    const getAllDescendants = (
+      node: import('./helpers/ScopeTreeManager').ScopeTreeNode,
+    ): Set<string> => {
+      const names = new Set<string>([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: Pick<
+        ScopeVariable,
+        'scopeNodeName' | 'schemaPath'
+      >[] = [];
+
+      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?: string) {
@@ -3603,6 +4117,54 @@ 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: string | null = 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
@@ -3875,10 +4437,32 @@ export class ScopeDataStructure {
     return scopeText;
   }
 
-  getEquivalentSignatureVariables() {
+  getEquivalentSignatureVariables(): Record<string, string | string[]> {
     const scopeNode = this.scopeNodes[this.scopeTreeManager.getRootName()];
 
-    const equivalentSignatureVariables: Record<string, string> = {};
+    const equivalentSignatureVariables: Record<string, string | string[]> = {};
+
+    // 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: string, value: string) => {
+      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,
     )) {
@@ -3887,7 +4471,7 @@ export class ScopeDataStructure {
         // 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)
@@ -3921,7 +4505,7 @@ export class ScopeDataStructure {
                 hookCallPath = dbEntry.sourceCandidates[0].schemaPath;
               }
             }
-            equivalentSignatureVariables[path] = hookCallPath;
+            addEquivalency(path, hookCallPath);
           }
         }
 
@@ -3935,10 +4519,17 @@ 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)
@@ -3951,7 +4542,7 @@ export class ScopeDataStructure {
           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)
@@ -3966,7 +4557,7 @@ export class ScopeDataStructure {
           !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)
@@ -3980,8 +4571,7 @@ export class ScopeDataStructure {
         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>()
@@ -3995,7 +4585,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);
           }
         }
       }
@@ -4026,8 +4616,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);
             }
           }
         }
@@ -4039,12 +4630,83 @@ export class ScopeDataStructure {
     // 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: string,
+      equivMap: Record<string, string | string[]>,
+    ): string | null => {
+      // Extract base variable from the path
+      const dotIndex = sourcePath.indexOf('.');
+      const bracketIndex = sourcePath.indexOf('[');
+
+      let baseVar: string;
+      let rest: string;
+
+      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(
+      for (const [varName, sourcePathOrArray] of Object.entries(
         equivalentSignatureVariables,
       )) {
+        // Handle arrays (OR expressions) by resolving each element
+        if (Array.isArray(sourcePathOrArray)) {
+          const resolvedArray: string[] = [];
+          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)
@@ -4106,6 +4768,8 @@ export class ScopeDataStructure {
               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;
@@ -4170,7 +4834,12 @@ export class ScopeDataStructure {
         }
 
         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;
@@ -4390,7 +5059,7 @@ export class ScopeDataStructure {
         path: string;
         conditionType: 'truthiness' | 'comparison' | 'switch';
         comparedValues?: string[];
-        location: 'if' | 'ternary' | 'logical-and' | 'switch';
+        location: 'if' | 'ternary' | 'logical-and' | 'switch' | 'unconditional';
       }>
     >,
   ): void {
@@ -4555,6 +5224,10 @@ export class ScopeDataStructure {
   getEnrichedConditionalUsages(): Record<string, EnrichedConditionalUsage[]> {
     const enriched: Record<string, EnrichedConditionalUsage[]> = {};
 
+    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
@@ -4563,10 +5236,69 @@ export class ScopeDataStructure {
 
       let sourceDataPath: string | undefined;
       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: string;
+        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: { schemaPath: string }) => s.schemaPath).join(', ')}]`,
+          );
+          const externalSource = sources.find(
+            (s: { schemaPath: string }) =>
+              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,
@@ -4914,11 +5646,22 @@ export class ScopeDataStructure {
           }
         }
 
+        // 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]) => {