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

package/analyzer-template/packages/analyze/src/lib/files/analyze/analyzeEntities/prepareDataStructures.ts

@@ -4,19 +4,31 @@ import { awsLog, awsLogDebugLevel } from '~codeyam/utils';
 import measureAndReportExecutionTime from '../../../utils/measureAndReportExecutionTime';
 
 import {
+  deduplicateFunctionSchemas,
+  detectWrapperRequirements,
   fillInDirectSchemaGapsAndUnknowns,
   generateEntityDataStructure,
-  deduplicateFunctionSchemas,
+  getConditionalUsages,
   getEquivalentSignatureVariables,
   getFunctionSignature,
   getReturnValue,
   getSourceEquivalencies,
   getUsageEquivalencies,
-  getConditionalUsages,
-  detectWrapperRequirements,
+  getConditionalEffects,
+  getCompoundConditionals,
+  getChildBoundaryGatingConditions,
+  getJsxRenderingUsages,
+  skipWorkerPool,
 } from '~codeyam/ai';
 import type { AnalysisOptions } from '../analyzeEntities';
 
+// 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.
@@ -27,15 +39,15 @@ export default async function prepareEntityDataStructures(
   projectAnalyzer: ProjectAnalyzer,
   options: AnalysisOptions,
 ): Promise<void> {
-  // 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 hasCache = !!entity.metadata?.isolatedDataStructure;
-      if (hasCache && !options.force && !options.forceAll) {
-        return;
-      }
+  const processEntity = async (entity: Entity) => {
+    // Check if already has cached data structure (unless force is set)
+    const hasCache = !!entity.metadata?.isolatedDataStructure;
+    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,
@@ -48,152 +60,272 @@ export default async function prepareEntityDataStructures(
               entityName: entity.name,
             },
           );
-          return;
-        }
+          // Still continue to PHASE 2 for server-only detection
+        } else {
+          const dataStructureInfo =
+            await getEntityDataStructureAndFunctionCalls({
+              entity,
+              fileAnalyzer,
+            });
 
-        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
+          } else {
+            const { isolatedDataStructure, functionCalls, callVariableNames } =
+              dataStructureInfo;
 
-        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}`,
-            );
-          }
-          return;
-        }
+            // Store data structure in 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: typeof isolatedDataStructure.dependencySchemas =
+              {};
+            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,
+                };
+              }
+            }
 
-        const { isolatedDataStructure, functionCalls, callVariableNames } =
-          dataStructureInfo;
-
-        // Store data structure in 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: typeof isolatedDataStructure.dependencySchemas =
-          {};
-        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: string[] = [];
+            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,
             };
-          }
-        }
 
-        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;
+            }
 
-        // 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 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;
+                }
+              }
+            }
           }
         }
+      } 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) {
+        // 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;
+        }
 
-        // 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;
-            }
-          }
+        // Never mock visual components - they render UI and should use real implementation
+        if (importedExport.entityType === 'visual') {
+          importedExport.isMocked = false;
+          continue;
         }
 
-        // Determine and mark mocked dependencies
-        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;
-            }
+        // 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();
 
-            importedExport.isMocked = mockedDependencies.some(
-              (dep) =>
-                dep.filePath === importedExport.filePath &&
-                dep.entityName === importedExport.name,
-            );
-          }
+        const isServerOnly = importedFileContent
+          ? isServerOnlyFile(importedFileContent)
+          : false;
+
+        if (importedFileContent && isServerOnly) {
+          importedExport.isMocked = true;
+          continue;
         }
 
-        // 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 info of infos) {
-            if (info.isMocked === undefined) {
-              // 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,
-                );
-              }
+        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 info of infos) {
+          if (info.isMocked === undefined || info.isMocked === null) {
+            // Browser globals should always be mocked
+            if (alwaysMockedBrowserGlobals.includes(path)) {
+              info.isMocked = true;
+            } else {
+              // 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 + '::')),
+              );
             }
           }
         }
-      } catch (error) {
-        console.warn(
-          `CodeYam: prepareEntityDataStructures: Error preparing ${entity.filePath}:${entity.name}:`,
-          error,
-        );
-        // Continue with other entities - this one will have empty schemas
       }
-    }),
+    } catch (error) {
+      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: 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`,
   );
 }
 
@@ -244,19 +376,33 @@ async function getEntityDataStructureAndFunctionCalls({
         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[importedExport.filePath] ||= {};
@@ -269,6 +415,170 @@ async function getEntityDataStructureAndFunctionCalls({
           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: Record<string, number> = {};
+            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: Record<string, string> = {};
+                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: Record<string, string> = {};
+
+            // 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: Record<string, string> | null = 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;
     },
     {} as {
@@ -289,6 +599,42 @@ async function getEntityDataStructureAndFunctionCalls({
     },
   );
 
+  // 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][efc.name] = {
+      signatureSchema: deduplicateFunctionSchemas(clonedSignatureSchema),
+      returnValueSchema: deduplicateFunctionSchemas(clonedReturnValueSchema),
+      usageEquivalencies: getUsageEquivalencies(dataStructure, efc.name) ?? {},
+      sourceEquivalencies:
+        getSourceEquivalencies(dataStructure, efc.name) ?? {},
+    };
+  }
+
   const rawReturnValue =
     getReturnValue(dataStructure, { fillInUnknowns: false }) ?? {};
 
@@ -301,15 +647,54 @@ async function getEntityDataStructureAndFunctionCalls({
   // 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: Record<string, string[]> = {};
@@ -322,31 +707,6 @@ async function getEntityDataStructureAndFunctionCalls({
         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: string[] = [];
@@ -392,6 +752,7 @@ async function getEntityDataStructureAndFunctionCalls({
       ) {
         variableNames.push(...aggregatedReceivingVariableNames);
       }
+
       if (variableNames.length > 0) {
         callVariableNames[entityName] = variableNames;
       }
@@ -589,9 +950,21 @@ export function determineMockedDependencies(entity: 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);
@@ -611,14 +984,28 @@ export function determineMockedDependencies(entity: Entity) {
         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({
@@ -631,3 +1018,32 @@ export function determineMockedDependencies(entity: 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: string): boolean {
+  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;
+}