@codeyam/codeyam-cli 0.1.0-staging.e38f7bd → 0.1.0-staging.e3d0ba6

package/packages/analyze/src/lib/files/analyze/analyzeEntities/prepareDataStructures.js

@@ -1,126 +1,186 @@
 import { awsLog, awsLogDebugLevel } from "../../../../../../../packages/utils/index.js";
 import measureAndReportExecutionTime from "../../../utils/measureAndReportExecutionTime.js";
-import { fillInDirectSchemaGapsAndUnknowns, generateEntityDataStructure, deduplicateFunctionSchemas, getEquivalentSignatureVariables, getFunctionSignature, getReturnValue, getSourceEquivalencies, getUsageEquivalencies, getConditionalUsages, detectWrapperRequirements, } from "../../../../../../../packages/ai/index.js";
+import { deduplicateFunctionSchemas, detectWrapperRequirements, fillInDirectSchemaGapsAndUnknowns, generateEntityDataStructure, getConditionalUsages, getEquivalentSignatureVariables, getFunctionSignature, getReturnValue, getSourceEquivalencies, getUsageEquivalencies, getConditionalEffects, getCompoundConditionals, getChildBoundaryGatingConditions, getJsxRenderingUsages, skipWorkerPool, } from "../../../../../../../packages/ai/index.js";
+// Set to true to process entities one at a time for easier debugging.
+const DEBUG_SEQUENTIAL_EXECUTION = false;
+// VERSION MARKER: server-only-detection-v2 (2025-12-28)
+// This version includes automatic detection of "use server" and "server-only" files
+// and runs server-only detection even for cached entities
 /**
  * PHASE 2: Prepare entity data structures
  * Generate data structures for all entities upfront, before graph traversal.
  * This ensures that data structure generation failures don't corrupt the traversal state.
  */
 export default async function prepareEntityDataStructures(allEntities, projectAnalyzer, options) {
-    // Process entities in parallel for speed
-    await Promise.all(Array.from(allEntities).map(async (entity) => {
-        // Skip if already has cached data structure (unless force is set)
+    const processEntity = async (entity) => {
+        // Check if already has cached data structure (unless force is set)
         const hasCache = !!entity.metadata?.isolatedDataStructure;
-        if (hasCache && !options.force && !options.forceAll) {
-            return;
-        }
-        try {
-            const fileAnalyzer = projectAnalyzer.getFileAnalyzerByPath(entity.resolvedFilePath ?? entity.filePath);
-            if (!fileAnalyzer) {
-                awsLog(`CodeYam: prepareEntityDataStructures: FileAnalyzer not found`, {
-                    entityFilePath: entity.filePath,
-                    entityName: entity.name,
-                });
-                return;
-            }
-            const dataStructureInfo = await getEntityDataStructureAndFunctionCalls({
-                entity,
-                fileAnalyzer,
-            });
-            if (!dataStructureInfo?.isolatedDataStructure) {
-                // Data structure generation failed - entity will proceed with empty schemas
-                // This is okay - the entity can still be analyzed, just without detailed type info
-                if (['visual', 'library'].includes(entity.entityType)) {
-                    // we'd really expect these to have data structures
-                    awsLog(`CodeYam: prepareEntityDataStructures: Failed to generate data structure for ${entity.filePath}:${entity.name}`);
+        const shouldRegenerateDataStructure = !hasCache || options.force || options.forceAll;
+        // PHASE 1: Generate data structure (only for non-cached entities or when forced)
+        // Wrapped in its own try-catch so PHASE 2 always runs even if this fails
+        if (shouldRegenerateDataStructure) {
+            try {
+                const fileAnalyzer = projectAnalyzer.getFileAnalyzerByPath(entity.resolvedFilePath ?? entity.filePath);
+                if (!fileAnalyzer) {
+                    awsLog(`CodeYam: prepareEntityDataStructures: FileAnalyzer not found`, {
+                        entityFilePath: entity.filePath,
+                        entityName: entity.name,
+                    });
+                    // Still continue to PHASE 2 for server-only detection
                 }
-                return;
-            }
-            const { isolatedDataStructure, functionCalls, callVariableNames } = dataStructureInfo;
-            // Store data structure in entity metadata
-            entity.metadata || (entity.metadata = {});
-            // Deep clone dependencySchemas to avoid shared references
-            // We need to clone because getReturnValue() returns direct references to schema objects
-            // and multiple entities might reference the same dependency
-            const clonedDependencySchemas = {};
-            for (const filePath in isolatedDataStructure.dependencySchemas) {
-                clonedDependencySchemas[filePath] = {};
-                for (const entityName in isolatedDataStructure.dependencySchemas[filePath]) {
-                    const depSchema = isolatedDataStructure.dependencySchemas[filePath][entityName];
-                    clonedDependencySchemas[filePath][entityName] = {
-                        signatureSchema: { ...depSchema.signatureSchema },
-                        returnValueSchema: { ...depSchema.returnValueSchema },
-                        usageEquivalencies: depSchema.usageEquivalencies,
-                        sourceEquivalencies: depSchema.sourceEquivalencies,
-                    };
-                }
-            }
-            entity.metadata.isolatedDataStructure = {
-                signatureSchema: deduplicateFunctionSchemas(isolatedDataStructure.signatureSchema),
-                returnValueSchema: deduplicateFunctionSchemas(isolatedDataStructure.returnValueSchema),
-                equivalentSignatureVariables: isolatedDataStructure.equivalentSignatureVariables,
-                dependencySchemas: clonedDependencySchemas,
-                environmentVariables: isolatedDataStructure.environmentVariables,
-                // Use enriched conditional usages with source tracing from analysis
-                conditionalUsages: isolatedDataStructure.conditionalUsages,
-            };
-            // Detect wrapper requirements (Context providers, etc.)
-            const wrapperRequirements = detectWrapperRequirements({
-                entity,
-                fileAnalyzer,
-            });
-            if (wrapperRequirements.length > 0) {
-                entity.metadata.wrapperRequirements = wrapperRequirements;
-            }
-            // Annotate imported exports with function call information
-            const importedExports = entity.metadata.importedExports ?? [];
-            for (const importedExport of importedExports) {
-                const relevantCalls = functionCalls[importedExport.name];
-                if (relevantCalls) {
-                    importedExport.calls = relevantCalls;
-                }
-                const relevantVariableNames = callVariableNames[importedExport.name];
-                if (relevantVariableNames) {
-                    importedExport.callVariableNames = relevantVariableNames;
-                }
-            }
-            // Annotate node module imports with function call information
-            for (const [path, infos] of Object.entries(entity.metadata.nodeModuleImports ?? {})) {
-                for (const info of infos) {
-                    const relevantCalls = functionCalls[info.name];
-                    if (relevantCalls) {
-                        info.calls = relevantCalls;
+                else {
+                    const dataStructureInfo = await getEntityDataStructureAndFunctionCalls({
+                        entity,
+                        fileAnalyzer,
+                    });
+                    if (!dataStructureInfo?.isolatedDataStructure) {
+                        // Data structure generation failed - entity will proceed with empty schemas
+                        // This is okay - the entity can still be analyzed, just without detailed type info
+                        if (['visual', 'library'].includes(entity.entityType)) {
+                            // we'd really expect these to have data structures
+                            awsLog(`CodeYam: prepareEntityDataStructures: Failed to generate data structure for ${entity.filePath}:${entity.name}`);
+                        }
+                        // Still continue to PHASE 2 for server-only detection
                     }
-                    const relevantVariableNames = callVariableNames[info.name];
-                    if (relevantVariableNames) {
-                        info.callVariableNames = relevantVariableNames;
+                    else {
+                        const { isolatedDataStructure, functionCalls, callVariableNames } = dataStructureInfo;
+                        // Store data structure in entity metadata
+                        entity.metadata || (entity.metadata = {});
+                        // Deep clone dependencySchemas to avoid shared references
+                        // We need to clone because getReturnValue() returns direct references to schema objects
+                        // and multiple entities might reference the same dependency
+                        const clonedDependencySchemas = {};
+                        for (const filePath in isolatedDataStructure.dependencySchemas) {
+                            clonedDependencySchemas[filePath] = {};
+                            for (const entityName in isolatedDataStructure.dependencySchemas[filePath]) {
+                                const depSchema = isolatedDataStructure.dependencySchemas[filePath][entityName];
+                                clonedDependencySchemas[filePath][entityName] = {
+                                    signatureSchema: { ...depSchema.signatureSchema },
+                                    returnValueSchema: { ...depSchema.returnValueSchema },
+                                    usageEquivalencies: depSchema.usageEquivalencies,
+                                    sourceEquivalencies: depSchema.sourceEquivalencies,
+                                };
+                            }
+                        }
+                        // LOGGING: Track dependencySchemas entity names for debugging :: format issues
+                        const allEntityNames = [];
+                        for (const filePath in clonedDependencySchemas) {
+                            for (const entityName in clonedDependencySchemas[filePath]) {
+                                allEntityNames.push(`${filePath}:${entityName}`);
+                            }
+                        }
+                        entity.metadata.isolatedDataStructure = {
+                            signatureSchema: deduplicateFunctionSchemas(isolatedDataStructure.signatureSchema),
+                            returnValueSchema: deduplicateFunctionSchemas(isolatedDataStructure.returnValueSchema),
+                            equivalentSignatureVariables: isolatedDataStructure.equivalentSignatureVariables,
+                            dependencySchemas: clonedDependencySchemas,
+                            environmentVariables: isolatedDataStructure.environmentVariables,
+                            // Use enriched conditional usages with source tracing from analysis
+                            conditionalUsages: isolatedDataStructure.conditionalUsages,
+                            // Include conditional effects for execution flow generation
+                            conditionalEffects: isolatedDataStructure.conditionalEffects,
+                            // Include compound conditionals for complete execution flow generation
+                            compoundConditionals: isolatedDataStructure.compoundConditionals,
+                            // Include root entity's equivalencies for merge step
+                            usageEquivalencies: isolatedDataStructure.usageEquivalencies,
+                            sourceEquivalencies: isolatedDataStructure.sourceEquivalencies,
+                            // Include child boundary gating conditions for child component flow merging
+                            childBoundaryGatingConditions: isolatedDataStructure.childBoundaryGatingConditions,
+                            // Include JSX rendering usages for array size and text length flow generation
+                            jsxRenderingUsages: isolatedDataStructure.jsxRenderingUsages,
+                        };
+                        // Detect wrapper requirements (Context providers, etc.)
+                        const wrapperRequirements = detectWrapperRequirements({
+                            entity,
+                            fileAnalyzer,
+                        });
+                        if (wrapperRequirements.length > 0) {
+                            entity.metadata.wrapperRequirements = wrapperRequirements;
+                        }
+                        // Annotate imported exports with function call information
+                        const importedExports = entity.metadata.importedExports ?? [];
+                        for (const importedExport of importedExports) {
+                            const relevantCalls = functionCalls[importedExport.name];
+                            if (relevantCalls) {
+                                importedExport.calls = relevantCalls;
+                            }
+                            const relevantVariableNames = callVariableNames[importedExport.name];
+                            if (relevantVariableNames) {
+                                importedExport.callVariableNames = relevantVariableNames;
+                            }
+                        }
+                        // Annotate node module imports with function call information
+                        for (const [path, infos] of Object.entries(entity.metadata.nodeModuleImports ?? {})) {
+                            for (const info of infos) {
+                                const relevantCalls = functionCalls[info.name];
+                                if (relevantCalls) {
+                                    info.calls = relevantCalls;
+                                }
+                                const relevantVariableNames = callVariableNames[info.name];
+                                if (relevantVariableNames) {
+                                    info.callVariableNames = relevantVariableNames;
+                                }
+                            }
+                        }
                     }
                 }
             }
-            // Determine and mark mocked dependencies
+            catch (phase1Error) {
+                console.warn(`CodeYam: prepareEntityDataStructures: PHASE 1 error for ${entity.filePath}:${entity.name}:`, phase1Error);
+                // Continue to PHASE 2 - server-only detection should still run
+            }
+        }
+        try {
+            // PHASE 2: Server-only detection and isMocked determination
+            // This runs for ALL entities, even those with cached data structures
+            // because server-only detection may have been added after the entity was cached
+            const importedExports = entity.metadata?.importedExports ?? [];
             const mockedDependencies = determineMockedDependencies(entity);
             for (const importedExport of importedExports) {
-                if (importedExport.isMocked === undefined) {
-                    // Never mock visual components - they render UI and should use real implementation
-                    if (importedExport.entityType === 'visual') {
-                        importedExport.isMocked = false;
-                        continue;
-                    }
-                    importedExport.isMocked = mockedDependencies.some((dep) => dep.filePath === importedExport.filePath &&
-                        dep.entityName === importedExport.name);
+                // Skip if already has a definitive isMocked value (true or false, not null)
+                // But re-check if isMocked is null or undefined - this handles previously cached entities
+                if (importedExport.isMocked === true ||
+                    importedExport.isMocked === false) {
+                    continue;
+                }
+                // Never mock visual components - they render UI and should use real implementation
+                if (importedExport.entityType === 'visual') {
+                    importedExport.isMocked = false;
+                    continue;
+                }
+                // Always mock imports from server-only files ("use server" or import "server-only")
+                // These files contain Server Actions or server-only code that cannot run on the client
+                const importedFilePath = importedExport.resolvedFilePath ?? importedExport.filePath;
+                const importedFileAnalyzer = projectAnalyzer.getFileAnalyzerByPath(importedFilePath);
+                // Use sourceFile.getText() which is always available, unlike file.content which is lazy-loaded
+                const importedFileContent = importedFileAnalyzer?.sourceFile?.getText();
+                const isServerOnly = importedFileContent
+                    ? isServerOnlyFile(importedFileContent)
+                    : false;
+                if (importedFileContent && isServerOnly) {
+                    importedExport.isMocked = true;
+                    continue;
                 }
+                const matchesMockedDep = mockedDependencies.some((dep) => dep.filePath === importedExport.filePath &&
+                    dep.entityName === importedExport.name);
+                importedExport.isMocked = matchesMockedDep;
             }
             // Browser globals that should always be mocked (they make network calls)
             const alwaysMockedBrowserGlobals = ['fetch', 'EventSource'];
-            for (const [path, infos] of Object.entries(entity.metadata.nodeModuleImports ?? {})) {
+            for (const [path, infos] of Object.entries(entity.metadata?.nodeModuleImports ?? {})) {
                 for (const info of infos) {
-                    if (info.isMocked === undefined) {
+                    if (info.isMocked === undefined || info.isMocked === null) {
                         // Browser globals should always be mocked
                         if (alwaysMockedBrowserGlobals.includes(path)) {
                             info.isMocked = true;
                         }
                         else {
-                            info.isMocked = mockedDependencies.some((dep) => dep.filePath === path && dep.entityName === info.name);
+                            // Check if this dependency should be mocked
+                            // Match both exact entityName and variable-qualified entityNames
+                            // e.g., "useFetcher" matches "useFetcher" OR "useFetcher::userFetcher"
+                            info.isMocked = mockedDependencies.some((dep) => dep.filePath === path &&
+                                (dep.entityName === info.name ||
+                                    dep.entityName.startsWith(info.name + '::')));
                         }
                     }
                 }
@@ -130,7 +190,43 @@ export default async function prepareEntityDataStructures(allEntities, projectAn
             console.warn(`CodeYam: prepareEntityDataStructures: Error preparing ${entity.filePath}:${entity.name}:`, error);
             // Continue with other entities - this one will have empty schemas
         }
-    }));
+    };
+    const entities = Array.from(allEntities);
+    // The worker thread creates its own ProjectAnalyzer (ts.Program) on first use,
+    // which takes 50-70s. For small entity counts the overhead far exceeds the actual
+    // processing time (<2s). Skip the worker and run on the main thread instead,
+    // reusing the existing ProjectAnalyzer.
+    const entitiesNeedingGeneration = entities.filter((e) => !e.metadata?.isolatedDataStructure || options.force || options.forceAll).length;
+    const WORKER_ENTITY_THRESHOLD = 500;
+    if (entitiesNeedingGeneration < WORKER_ENTITY_THRESHOLD) {
+        console.log(`CodeYam: Skipping worker thread for DS prep (${entitiesNeedingGeneration} entities < ${WORKER_ENTITY_THRESHOLD} threshold)`);
+        skipWorkerPool();
+    }
+    awsLogDebugLevel(1, `Preparing data structures for ${entities.length} entities (${entitiesNeedingGeneration} need generation)...`);
+    const startTime = Date.now();
+    let completedCount = 0;
+    // Wrap processEntity to track progress
+    const processEntityWithProgress = async (entity) => {
+        await processEntity(entity);
+        completedCount++;
+        // Emit progress every 10 entities
+        if (completedCount % 10 === 0) {
+            awsLogDebugLevel(1, `Preparing data structures... (${completedCount}/${entities.length})`);
+        }
+    };
+    const sequential = DEBUG_SEQUENTIAL_EXECUTION || options.sequentialDataStructurePrep;
+    if (sequential) {
+        // Sequential execution for debugging - process one entity at a time
+        for (const entity of entities) {
+            await processEntityWithProgress(entity);
+        }
+    }
+    else {
+        // Parallel execution for speed
+        await Promise.all(entities.map(processEntityWithProgress));
+    }
+    const elapsed = Date.now() - startTime;
+    awsLogDebugLevel(1, `Data structure preparation complete: ${entities.length} entities in ${elapsed}ms`);
 }
 /**
  * Helper: Generate data structure and extract function call information for an entity
@@ -160,17 +256,26 @@ async function getEntityDataStructureAndFunctionCalls({ entity, fileAnalyzer, })
         const signatureSchema = getFunctionSignature(dataStructure, {
             functionName: importedExport.name,
         });
-        // If no signature found, this function doesn't exist in the analysis
-        if (!signatureSchema) {
-            return acc;
-        }
         const returnValueSchema = getReturnValue(dataStructure, {
             functionName: importedExport.name,
         });
+        // If neither signature nor return value found, check if this function has matching
+        // external function calls. External functions (like useLoaderData from react-router)
+        // don't have entries in functionResults, so getReturnValue returns null for them.
+        // But their return values ARE traced in externalFunctionCalls via perVariableSchemas.
+        // We need to check for matching calls before skipping.
+        if (!signatureSchema && !returnValueSchema) {
+            const hasMatchingExternalCall = dataStructure.externalFunctionCalls?.some((fc) => fc.name === importedExport.name ||
+                fc.name.startsWith(importedExport.name + '<'));
+            // Only skip if there are no matching external function calls
+            if (!hasMatchingExternalCall) {
+                return acc;
+            }
+        }
         // Clone schemas before deduplication to avoid mutating shared references
         // getReturnValue() and getFunctionSignature() return direct references, so we need
         // to clone them before passing to deduplicateFunctionSchemas (which may mutate)
-        const clonedSignatureSchema = { ...signatureSchema };
+        const clonedSignatureSchema = { ...(signatureSchema ?? {}) };
         const clonedReturnValueSchema = { ...(returnValueSchema ?? {}) };
         acc[_a = importedExport.filePath] || (acc[_a] = {});
         acc[importedExport.filePath][importedExport.name] = {
@@ -179,8 +284,164 @@ async function getEntityDataStructureAndFunctionCalls({ entity, fileAnalyzer, })
             usageEquivalencies: getUsageEquivalencies(dataStructure, importedExport.name) ?? {},
             sourceEquivalencies: getSourceEquivalencies(dataStructure, importedExport.name) ?? {},
         };
+        // Also create variable-qualified entries to preserve distinct return type schemas
+        // when the same function is called multiple times with different type parameters
+        // (e.g., useFetcher<UserData>() vs useFetcher<ReportData>()).
+        //
+        // Each parameterized call is a SEPARATE entry in externalFunctionCalls, so we need
+        // to iterate over ALL matching calls (not just the first one).
+        const matchingCalls = dataStructure.externalFunctionCalls.filter((fc) => fc.name === importedExport.name ||
+            fc.name.startsWith(importedExport.name + '<'));
+        for (const efc of matchingCalls) {
+            // Check if this call has perVariableSchemas (multiple calls with variable tracking)
+            if (efc?.perVariableSchemas) {
+                // Check if perVariableSchemas has indexed keys (e.g., "fetcher[1]") which indicates
+                // variable reuse with DIFFERENT call signatures (e.g., let fetcher = useFetcher<A>(); fetcher = useFetcher<B>();)
+                // In this case, we need to create SEPARATE entries for each call signature.
+                const perVarKeys = Object.keys(efc.perVariableSchemas);
+                const hasIndexedKeys = perVarKeys.some((key) => /\[\d+\]$/.test(key));
+                if (hasIndexedKeys &&
+                    efc.callSignatureToVariable &&
+                    efc.allCallSignatures) {
+                    // Variable reuse case: create separate entries for each call signature
+                    // Map from call signature to its variable key in perVariableSchemas
+                    // e.g., useFetcher<ConfigData>() -> 'fetcher', useFetcher<SettingsData>() -> 'fetcher[1]'
+                    const varNameCounts = {};
+                    for (const callSig of efc.allCallSignatures) {
+                        const varName = efc.callSignatureToVariable[callSig];
+                        if (!varName)
+                            continue;
+                        // Track occurrence count for this variable name
+                        const occurrence = varNameCounts[varName] ?? 0;
+                        varNameCounts[varName] = occurrence + 1;
+                        // Get the key in perVariableSchemas (indexed if reused)
+                        const perVarKey = occurrence === 0 ? varName : `${varName}[${occurrence}]`;
+                        const varSchema = efc.perVariableSchemas[perVarKey];
+                        if (varSchema && Object.keys(varSchema).length > 0) {
+                            // Create entry with this call signature as the key
+                            const rewrittenSchema = {};
+                            rewrittenSchema[`${callSig}.functionCallReturnValue`] =
+                                'object';
+                            for (const [path, type] of Object.entries(varSchema)) {
+                                const rewrittenPath = path.startsWith(callSig)
+                                    ? path
+                                    : `${callSig}.${path}`;
+                                rewrittenSchema[rewrittenPath] = type;
+                            }
+                            acc[importedExport.filePath][callSig] = {
+                                signatureSchema: deduplicateFunctionSchemas({
+                                    ...signatureSchema,
+                                }),
+                                returnValueSchema: deduplicateFunctionSchemas(rewrittenSchema),
+                                usageEquivalencies: getUsageEquivalencies(dataStructure, importedExport.name) ??
+                                    {},
+                                sourceEquivalencies: getSourceEquivalencies(dataStructure, importedExport.name) ?? {},
+                            };
+                        }
+                    }
+                }
+                else {
+                    // Destructuring case: const { a, b, c } = useLoaderData()
+                    // Merge all variable schemas into a single entry with the call signature as key
+                    const callSignatureKey = efc.callSignature;
+                    // Merge all variable schemas by prepending the call signature to each path.
+                    // perVariableSchemas paths are like "functionCallReturnValue.entities.sha"
+                    // We need to prefix them with the call signature to get:
+                    // "useLoaderData<typeof loader>().functionCallReturnValue.entities.sha"
+                    const mergedReturnValueSchema = {};
+                    // Set the top-level return value as object since it contains named properties
+                    mergedReturnValueSchema[`${callSignatureKey}.functionCallReturnValue`] = 'object';
+                    for (const [varName, perVarSchema] of Object.entries(efc.perVariableSchemas)) {
+                        for (const [path, type] of Object.entries(perVarSchema)) {
+                            // Only prepend the call signature if the path doesn't already have it.
+                            // perVariableSchemas paths may already include the call signature prefix
+                            // (e.g., "useCustomSizes(projectSlug).functionCallReturnValue.customSizes")
+                            // depending on how they were built. If so, use the path as-is.
+                            const rewrittenPath = path.startsWith(callSignatureKey)
+                                ? path
+                                : `${callSignatureKey}.${path}`;
+                            mergedReturnValueSchema[rewrittenPath] = type;
+                        }
+                    }
+                    acc[importedExport.filePath][callSignatureKey] = {
+                        signatureSchema: deduplicateFunctionSchemas({
+                            ...signatureSchema,
+                        }),
+                        returnValueSchema: deduplicateFunctionSchemas(mergedReturnValueSchema),
+                        usageEquivalencies: getUsageEquivalencies(dataStructure, importedExport.name) ?? {},
+                        sourceEquivalencies: getSourceEquivalencies(dataStructure, importedExport.name) ??
+                            {},
+                    };
+                }
+            }
+            else if (efc?.receivingVariableNames?.length === 1) {
+                // For parameterized calls like useFetcher<UserData>(), each is a separate entry
+                // with a single receivingVariableName. Use the call signature as the key.
+                const varName = efc.receivingVariableNames[0];
+                // Use the call signature as the key (e.g., "useFetcher<UserData>()")
+                const callSignatureKey = efc.callSignature;
+                // PREFER perVariableSchemas over getReturnValue() when available
+                // perVariableSchemas has the SPECIFIC schema for this parameterized call,
+                // while getReturnValue() may return merged schemas from multiple calls
+                let parameterizedReturnValue = null;
+                if (efc.perVariableSchemas && efc.perVariableSchemas[varName]) {
+                    // Use the specific schema from perVariableSchemas
+                    parameterizedReturnValue = efc.perVariableSchemas[varName] ?? null;
+                }
+                // Fallback to getReturnValue if perCallSignatureSchemas not available
+                if (!parameterizedReturnValue) {
+                    parameterizedReturnValue = getReturnValue(dataStructure, {
+                        functionName: efc.name, // Use the full parameterized name
+                    });
+                }
+                if (parameterizedReturnValue &&
+                    Object.keys(parameterizedReturnValue).length > 0) {
+                    acc[importedExport.filePath][callSignatureKey] = {
+                        signatureSchema: deduplicateFunctionSchemas({
+                            ...signatureSchema,
+                        }),
+                        returnValueSchema: deduplicateFunctionSchemas({
+                            ...parameterizedReturnValue,
+                        }),
+                        usageEquivalencies: getUsageEquivalencies(dataStructure, importedExport.name) ?? {},
+                        sourceEquivalencies: getSourceEquivalencies(dataStructure, importedExport.name) ??
+                            {},
+                    };
+                }
+            }
+        }
         return acc;
     }, {});
+    // Add same-file child components to dependencySchemas.
+    // Same-file components (e.g., AgentCard defined in the same file as AgentTranscriptsPage)
+    // appear in externalFunctionCalls and functionResults but NOT in importedExports or
+    // nodeModuleImports. Without this, their signatures are missing from dependencySchemas
+    // and enrichArrayTypesFromChildSignatures can't find child component field accesses.
+    const allDependencyNames = new Set(allDependencies.map((d) => d.name));
+    for (const efc of dataStructure.externalFunctionCalls) {
+        // Skip if already covered by importedExports or nodeModuleImports
+        if (allDependencyNames.has(efc.name))
+            continue;
+        const signatureSchema = getFunctionSignature(dataStructure, {
+            functionName: efc.name,
+        });
+        const returnValueSchema = getReturnValue(dataStructure, {
+            functionName: efc.name,
+        });
+        // Only add if we have signature or return value data
+        if (!signatureSchema && !returnValueSchema)
+            continue;
+        const clonedSignatureSchema = { ...(signatureSchema ?? {}) };
+        const clonedReturnValueSchema = { ...(returnValueSchema ?? {}) };
+        const entityFilePath = entity.filePath;
+        dependencySchemas[entityFilePath] || (dependencySchemas[entityFilePath] = {});
+        dependencySchemas[entityFilePath][efc.name] = {
+            signatureSchema: deduplicateFunctionSchemas(clonedSignatureSchema),
+            returnValueSchema: deduplicateFunctionSchemas(clonedReturnValueSchema),
+            usageEquivalencies: getUsageEquivalencies(dataStructure, efc.name) ?? {},
+            sourceEquivalencies: getSourceEquivalencies(dataStructure, efc.name) ?? {},
+        };
+    }
     const rawReturnValue = getReturnValue(dataStructure, { fillInUnknowns: false }) ?? {};
     // Clone root function schemas before deduplication to avoid mutating shared references
     const rawSignature = getFunctionSignature(dataStructure, { fillInUnknowns: false }) ?? {};
@@ -188,13 +449,42 @@ async function getEntityDataStructureAndFunctionCalls({ entity, fileAnalyzer, })
     const clonedRawReturnValue = { ...rawReturnValue };
     // Get enriched conditional usages with source tracing
     const conditionalUsages = getConditionalUsages(dataStructure);
+    // Get conditional effects (setter calls inside conditionals)
+    const conditionalEffects = getConditionalEffects(dataStructure);
+    // Get compound conditionals (grouped conditions that must all be true)
+    const compoundConditionals = getCompoundConditionals(dataStructure);
+    const rawUsageEquivalencies = getUsageEquivalencies(dataStructure);
+    const rawSourceEquivalencies = getSourceEquivalencies(dataStructure);
+    // Get child boundary gating conditions for child component flow merging
+    const childBoundaryGatingConditions = getChildBoundaryGatingConditions(dataStructure);
+    // Get JSX rendering usages for array size and text length flow generation
+    const jsxRenderingUsages = getJsxRenderingUsages(dataStructure);
+    const equivalentSignatureVariables = getEquivalentSignatureVariables(dataStructure);
     const isolatedDataStructure = {
         signatureSchema: deduplicateFunctionSchemas(clonedRawSignature),
         returnValueSchema: deduplicateFunctionSchemas(clonedRawReturnValue),
-        equivalentSignatureVariables: getEquivalentSignatureVariables(dataStructure),
+        equivalentSignatureVariables,
         dependencySchemas,
         environmentVariables: dataStructure.environmentVariables,
         conditionalUsages: Object.keys(conditionalUsages).length > 0 ? conditionalUsages : undefined,
+        // Include conditional effects for execution flow generation
+        conditionalEffects: conditionalEffects.length > 0 ? conditionalEffects : undefined,
+        // Include compound conditionals for complete execution flow generation
+        // These capture grouped conditions like (a || b) && !c && !d
+        compoundConditionals: compoundConditionals.length > 0 ? compoundConditionals : undefined,
+        // Include root entity's equivalencies so they can be used during merge.
+        // These show how the parent's data flows to/from child components.
+        // E.g., for SurveysList, usageEquivalencies shows surveys[] → SurveyCard().signature[0].survey
+        usageEquivalencies: rawUsageEquivalencies ?? {},
+        sourceEquivalencies: rawSourceEquivalencies ?? {},
+        // Include child boundary gating conditions for child component flow merging
+        // Maps child component names to the conditions that must be true for them to render
+        childBoundaryGatingConditions: Object.keys(childBoundaryGatingConditions).length > 0
+            ? childBoundaryGatingConditions
+            : undefined,
+        // Include JSX rendering usages for array size and text length flow generation
+        // These track arrays rendered via .map() and strings interpolated in JSX
+        jsxRenderingUsages: jsxRenderingUsages.length > 0 ? jsxRenderingUsages : undefined,
     };
     const functionCalls = {};
     const callVariableNames = {};
@@ -202,22 +492,6 @@ async function getEntityDataStructureAndFunctionCalls({ entity, fileAnalyzer, })
     for (const filePath in dependencySchemas) {
         for (const entityName in dependencySchemas[filePath]) {
             const matchingCalls = dataStructure.externalFunctionCalls.filter((efc) => efc.callSignature.startsWith(entityName));
-            // DEBUG: Log external function calls info for useFetcher
-            if (entityName === 'useFetcher' || entityName.includes('Fetcher')) {
-                console.log('CodeYam DEBUG prepareDataStructures:', JSON.stringify({
-                    entityName,
-                    filePath,
-                    totalExternalFunctionCalls: dataStructure.externalFunctionCalls.length,
-                    matchingCallsCount: matchingCalls.length,
-                    matchingCalls: matchingCalls.map((efc) => ({
-                        name: efc.name,
-                        callSignature: efc.callSignature,
-                        allCallSignatures: efc.allCallSignatures,
-                        receivingVariableNames: efc.receivingVariableNames,
-                        callSignatureToVariable: efc.callSignatureToVariable,
-                    })),
-                }, null, 2));
-            }
             // Collect all call signatures from all matching efc entries
             // Each efc may have just one callSignature, or allCallSignatures if merged
             const allSignatures = [];
@@ -430,7 +704,17 @@ export function determineMockedDependencies(entity) {
             // A schema with only "EntityName(): function" just indicates the entity is callable,
             // it doesn't mean there's actual return data to mock
             const hasReturnValue = hasActualReturnValueData(entityReturnValueSchema);
-            const complexReturnValue = Object.values(entityReturnValueSchema ?? {}).some((value) => value === 'object' || value === 'array');
+            // Check for complex return types (object/array), accounting for nullable types
+            // e.g., 'object', 'object | null', 'array | undefined' should all count as complex.
+            // Also detect when functionCallReturnValue has nested child properties — this
+            // proves it's a structured type even if its declared type is still 'unknown'.
+            const returnValueKeys = Object.keys(entityReturnValueSchema ?? {});
+            const complexReturnValue = Object.values(entityReturnValueSchema ?? {}).some((value) => {
+                const baseType = value?.split(' | ')[0];
+                return baseType === 'object' || baseType === 'array';
+            }) ||
+                returnValueKeys.some((key) => key.includes('functionCallReturnValue.') ||
+                    key.includes('functionCallReturnValue['));
             // Check if this is a validation function that should always be mocked
             const isValidationFn = isValidationFunction(entityName);
             // Check if entity has chained method calls but no return value
@@ -443,13 +727,25 @@ export function determineMockedDependencies(entity) {
             // If so, we should NOT mock this entity - jsx-components like React Context's
             // Provider/Consumer should use the original, not be mocked
             const onlyHasJsxComponents = allFunctionsAreJsxComponents(entityReturnValueSchema);
+            // Check if returnValueSchema is completely empty (no traced calls at all)
+            // This indicates a side-effect function that we couldn't trace
+            const returnValueSchemaEmpty = Object.keys(entityReturnValueSchema ?? {}).length === 0;
             const entityShouldBeMocked = !onlyHasJsxComponents &&
                 (isValidationFn ||
                     hasChainedCallsWithNoReturn ||
+                    // If entity takes no args AND has return value, it reads from external source
+                    // Examples: useParams(), useAuth(), getConfig()
+                    (emptySignature && hasReturnValue) ||
+                    // If entity takes no args AND returnValueSchema is completely empty,
+                    // it's a side-effect function calling external services
+                    // Examples: logPageView(), initializeAnalytics(), trackEvent()
+                    // NOTE: We don't mock entities that have function markers but no return value
+                    // (like React components: FileProvider() has 'function' type but no return data)
+                    (emptySignature && returnValueSchemaEmpty) ||
                     ((signatureHasFunctions || returnValueHasFunctions) &&
                         hasReturnValue &&
-                        ((emptySignature && hasReturnValue) ||
-                            (!complexSignature && complexReturnValue))));
+                        !complexSignature &&
+                        complexReturnValue));
             if (entityShouldBeMocked) {
                 mockedEntities.push({
                     filePath,
@@ -460,4 +756,27 @@ export function determineMockedDependencies(entity) {
     }
     return mockedEntities;
 }
+/**
+ * Check if a file is server-only based on its content.
+ *
+ * A file is considered server-only if it:
+ * 1. Starts with "use server" directive (Server Actions in Next.js)
+ * 2. Contains import "server-only" (explicit server-only marker)
+ *
+ * Server-only files should always be mocked when imported by client components
+ * because they contain code that cannot run in the browser.
+ */
+export function isServerOnlyFile(fileContent) {
+    const trimmed = fileContent.trimStart();
+    // Check for "use server" directive at the start of the file
+    if (trimmed.startsWith('"use server"') ||
+        trimmed.startsWith("'use server'")) {
+        return true;
+    }
+    // Check for server-only import anywhere in the file
+    if (/import\s+["']server-only["']/.test(fileContent)) {
+        return true;
+    }
+    return false;
+}
 //# sourceMappingURL=prepareDataStructures.js.map