@codeyam/codeyam-cli 0.1.0-staging.1669d45 → 0.1.0-staging.2a88920

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([
@@ -203,6 +216,11 @@ export class ScopeDataStructure {
          * Maps child component name to the conditions that must be true for it to render.
          */
         this.rawChildBoundaryGatingConditions = {};
+        /**
+         * JSX rendering usages collected during AST analysis.
+         * Tracks arrays rendered via .map() and strings interpolated in JSX.
+         */
+        this.rawJsxRenderingUsages = [];
         this.lastAddToSchemaId = 0;
         this.lastEquivalencyId = 0;
         this.lastEquivalencyDatabaseId = 0;
@@ -1070,21 +1088,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;
@@ -1096,9 +1129,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);
@@ -1109,116 +1149,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);
+                    }
                 }
             }
         }
@@ -1362,8 +1422,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;
                 }
@@ -1386,22 +1453,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[');
@@ -1413,33 +1490,36 @@ export class ScopeDataStructure {
             const isReduceSourceSub = reduceSourceVar &&
                 (subPath.startsWith(reduceSourceVar + '.') ||
                     subPath.startsWith(reduceSourceVar + '['));
-            if (typeof subValue !== 'string' ||
-                (!isReturnValueSub && !isAliasSub && !isReduceSourceSub))
+            if (!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))
-                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);
+            }
         }
     }
     /**
@@ -1471,7 +1551,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),
@@ -1950,9 +2037,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);
                 }
             }
@@ -2362,15 +2510,131 @@ export class ScopeDataStructure {
         if (!scopeNode) {
             return {};
         }
-        const entries = this.equivalencyDatabase.filter((entry) => entry.usages.some((usage) => usage.scopeNodeName === scopeNode.name));
+        // 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];
+        };
         return entries.reduce((acc, entry) => {
             var _a;
             if (entry.sourceCandidates.length === 0)
                 return acc;
-            const usages = entry.usages.filter((u) => u.scopeNodeName === scopeNode.name);
+            const usages = entry.usages.filter(usageMatchesScope);
             for (const usage of usages) {
                 acc[_a = usage.schemaPath] || (acc[_a] = []);
-                acc[usage.schemaPath].push(...entry.sourceCandidates);
+                // Resolve each source candidate through the equivalency chain
+                for (const source of entry.sourceCandidates) {
+                    const resolvedSources = resolveToSignature(source, new Set());
+                    acc[usage.schemaPath].push(...resolvedSources);
+                }
             }
             return acc;
         }, {});
@@ -2659,13 +2923,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
@@ -2675,11 +2961,25 @@ export class ScopeDataStructure {
                 // "useFetcher<...>().state" for execution flow validation
                 if (equivalentValue.schemaPath.endsWith('.functionCallReturnValue')) {
                     // Extract the hook call path (everything before .functionCallReturnValue)
-                    const hookCallPath = equivalentValue.schemaPath.slice(0, -'.functionCallReturnValue'.length);
+                    let hookCallPath = equivalentValue.schemaPath.slice(0, -'.functionCallReturnValue'.length);
                     // Only include if it looks like a hook call (contains parentheses)
                     // and the variable name (path) is a simple identifier (no dots)
                     if (hookCallPath.includes('(') && !path.includes('.')) {
-                        equivalentSignatureVariables[path] = hookCallPath;
+                        // Special case: If hookCallPath is a callback scope (cyScope pattern),
+                        // trace through it to find what the callback actually returns.
+                        // This handles useState(() => { return prop; }) patterns.
+                        const cyScopeMatch = hookCallPath.match(/^(cyScope\d+)\(\)$/);
+                        if (cyScopeMatch) {
+                            // Use the equivalency database to trace the callback's return value
+                            // to its actual source (e.g., viewModeFromUrl -> segments -> params -> useParams)
+                            const dbEntry = this.getEquivalenciesDatabaseEntry(scopeNode.name, // Component scope
+                            path);
+                            if (dbEntry?.sourceCandidates?.length > 0) {
+                                // Use the traced source instead of the callback scope
+                                hookCallPath = dbEntry.sourceCandidates[0].schemaPath;
+                            }
+                        }
+                        addEquivalency(path, hookCallPath);
                     }
                 }
                 // Case 3: Destructured variables from local variables
@@ -2691,10 +2991,8 @@ 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;
-                    }
+                    // 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:
@@ -2705,7 +3003,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)
@@ -2718,7 +3016,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:
@@ -2730,8 +3028,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>()
@@ -2742,7 +3039,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);
                     }
                 }
             }
@@ -2769,8 +3066,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);
                         }
                     }
                 }
@@ -2780,9 +3078,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)
@@ -2835,6 +3196,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;
@@ -2845,6 +3209,34 @@ export class ScopeDataStructure {
                             }
                         }
                     }
+                    // Fix 38: Handle cyScope lazy initializer return values
+                    // When we have viewMode -> cyScope20(), trace through to find what cyScope20 returns.
+                    // The lazy initializer's return value should be the controllable data source.
+                    // Pattern: cyScopeN() where N is a number
+                    const cyScopeMatch = sourcePath.match(/^(cyScope\d+)\(\)$/);
+                    if (cyScopeMatch) {
+                        const cyScopeName = cyScopeMatch[1];
+                        const cyScopeNode = this.scopeNodes[cyScopeName];
+                        if (cyScopeNode?.equivalencies) {
+                            // Look for returnValue equivalency in the cyScope
+                            const returnValueEquivs = cyScopeNode.equivalencies['returnValue'];
+                            if (returnValueEquivs && returnValueEquivs.length > 0) {
+                                // Get the first return value source
+                                const returnSource = returnValueEquivs[0].schemaPath;
+                                // If the return source is a simple variable (not a complex path),
+                                // resolve varName directly to that variable
+                                if (returnSource &&
+                                    !returnSource.includes('(') &&
+                                    !returnSource.includes('[')) {
+                                    // Update varName to point to the return source
+                                    if (equivalentSignatureVariables[varName] !== returnSource) {
+                                        equivalentSignatureVariables[varName] = returnSource;
+                                        changed = true;
+                                    }
+                                }
+                            }
+                        }
+                    }
                     continue;
                 }
                 // Check if the source path starts with a variable that's also in the map
@@ -2862,7 +3254,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;
@@ -3169,6 +3567,26 @@ export class ScopeDataStructure {
         }
         return enriched;
     }
+    /**
+     * Add JSX rendering usages from AST analysis.
+     * These track arrays rendered via .map() and strings interpolated in JSX.
+     */
+    addJsxRenderingUsages(usages) {
+        // Add usages, avoiding duplicates based on path and renderingType
+        for (const usage of usages) {
+            const exists = this.rawJsxRenderingUsages.some((existing) => existing.path === usage.path &&
+                existing.renderingType === usage.renderingType);
+            if (!exists) {
+                this.rawJsxRenderingUsages.push(usage);
+            }
+        }
+    }
+    /**
+     * Get JSX rendering usages collected during analysis.
+     */
+    getJsxRenderingUsages() {
+        return this.rawJsxRenderingUsages;
+    }
     toSerializable() {
         // Helper to clean cyScope and cyDuplicateKey from a string for output
         const cleanCyScope = (str) => this.replaceCyScopeInString(str).replace(/::cyDuplicateKey\d+::/g, '');
@@ -3553,6 +3971,10 @@ export class ScopeDataStructure {
         const childBoundaryGatingConditions = Object.keys(enrichedGatingConditions).length > 0
             ? enrichedGatingConditions
             : undefined;
+        // Get JSX rendering usages (arrays via .map(), strings via interpolation)
+        const jsxRenderingUsages = this.rawJsxRenderingUsages.length > 0
+            ? this.rawJsxRenderingUsages
+            : undefined;
         return {
             externalFunctionCalls: deduplicatedExternalFunctionCalls,
             rootFunction,
@@ -3563,6 +3985,7 @@ export class ScopeDataStructure {
             conditionalEffects,
             compoundConditionals,
             childBoundaryGatingConditions,
+            jsxRenderingUsages,
         };
     }
     // ═══════════════════════════════════════════════════════════════════════════