@codeyam/codeyam-cli 0.1.0-staging.bbe4da9 → 0.1.0-staging.d0ad4ae

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

@@ -17,6 +17,10 @@ import {
 } from '~codeyam/ai';
 import type { AnalysisOptions } from '../analyzeEntities';
 
+// 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.
@@ -30,142 +34,220 @@ export default async function prepareEntityDataStructures(
   // 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)
+      // 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,
-            },
+      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,
           );
-          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
+          if (!fileAnalyzer) {
             awsLog(
-              `CodeYam: prepareEntityDataStructures: Failed to generate data structure for ${entity.filePath}:${entity.name}`,
+              `CodeYam: prepareEntityDataStructures: FileAnalyzer not found`,
+              {
+                entityFilePath: entity.filePath,
+                entityName: entity.name,
+              },
             );
-          }
-          return;
-        }
+            // Still continue to PHASE 2 for server-only detection
+          } 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
+            } else {
+              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,
+                  };
+                }
+              }
 
-        const { isolatedDataStructure, functionCalls } = 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 root entity's equivalencies for merge step
+                usageEquivalencies: isolatedDataStructure.usageEquivalencies,
+                sourceEquivalencies: isolatedDataStructure.sourceEquivalencies,
+              };
+
+              // Detect wrapper requirements (Context providers, etc.)
+              const wrapperRequirements = detectWrapperRequirements({
+                entity,
+                fileAnalyzer,
+              });
+              if (wrapperRequirements.length > 0) {
+                entity.metadata.wrapperRequirements = wrapperRequirements;
+              }
 
-        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,
-        };
+              // 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;
+                }
+              }
 
-        // Detect wrapper requirements (Context providers, etc.)
-        const wrapperRequirements = detectWrapperRequirements({
-          entity,
-          fileAnalyzer,
-        });
-        if (wrapperRequirements.length > 0) {
-          entity.metadata.wrapperRequirements = wrapperRequirements;
+              // 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
         }
+      }
 
-        // Annotate imported exports with function call information
-        const importedExports = entity.metadata.importedExports ?? [];
+      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) {
-          const relevantCalls = functionCalls[importedExport.name];
-          if (relevantCalls) {
-            importedExport.calls = relevantCalls;
+          // 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;
-            }
+          // 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) {
-            importedExport.isMocked = mockedDependencies.some(
-              (dep) =>
-                dep.filePath === importedExport.filePath &&
-                dep.entityName === importedExport.name,
-            );
+          // 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 ?? {},
+          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 {
+                // 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.filePath === path &&
+                    (dep.entityName === info.name ||
+                      dep.entityName.startsWith(info.name + '::')),
                 );
               }
             }
@@ -229,19 +311,21 @@ 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, this function doesn't exist in the analysis.
+      // We need to check BOTH because hooks like useParams() have no signature (no arguments)
+      // but DO have a return value that needs to be mocked.
+      if (!signatureSchema && !returnValueSchema) {
+        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] ||= {};
@@ -254,6 +338,108 @@ 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 same signature)
+        // This is the destructuring case: const { a, b, c } = useLoaderData()
+        // Instead of creating ::variable qualified keys, merge into a single entry
+        // with the call signature as key and named properties in the schema
+        if (efc?.perVariableSchemas) {
+          // Use the call signature as the key (e.g., "useLoaderData<typeof loader>()")
+          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)) {
+              // Prepend the call signature to the path
+              // Input: "functionCallReturnValue.entities.sha"
+              // Output: "useLoaderData<typeof loader>().functionCallReturnValue.entities.sha"
+              const rewrittenPath = `${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 {
@@ -286,6 +472,9 @@ async function getEntityDataStructureAndFunctionCalls({
   // Get enriched conditional usages with source tracing
   const conditionalUsages = getConditionalUsages(dataStructure);
 
+  const rawUsageEquivalencies = getUsageEquivalencies(dataStructure);
+  const rawSourceEquivalencies = getSourceEquivalencies(dataStructure);
+
   const isolatedDataStructure = {
     signatureSchema: deduplicateFunctionSchemas(clonedRawSignature),
     returnValueSchema: deduplicateFunctionSchemas(clonedRawReturnValue),
@@ -295,20 +484,76 @@ async function getEntityDataStructureAndFunctionCalls({
     environmentVariables: dataStructure.environmentVariables,
     conditionalUsages:
       Object.keys(conditionalUsages).length > 0 ? conditionalUsages : 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 ?? {},
   };
 
   const functionCalls: Record<string, string[]> = {};
+  const callVariableNames: Record<string, string[]> = {};
 
   // Note: externalFunctionCalls is needed for callSignature info, which isn't exposed through helpers
   for (const filePath in dependencySchemas) {
     for (const entityName in dependencySchemas[filePath]) {
-      functionCalls[entityName] = dataStructure.externalFunctionCalls
-        .filter((efc) => efc.callSignature.startsWith(entityName))
-        .map((efc) => efc.callSignature);
+      const matchingCalls = dataStructure.externalFunctionCalls.filter((efc) =>
+        efc.callSignature.startsWith(entityName),
+      );
+
+      // Collect all call signatures from all matching efc entries
+      // Each efc may have just one callSignature, or allCallSignatures if merged
+      const allSignatures: string[] = [];
+      for (const efc of matchingCalls) {
+        if (efc.allCallSignatures) {
+          allSignatures.push(...efc.allCallSignatures);
+        } else {
+          allSignatures.push(efc.callSignature);
+        }
+      }
+      functionCalls[entityName] = allSignatures;
+
+      // Aggregate callSignatureToVariable maps across all matching calls
+      // This handles the case where tracking data ends up on just one efc entry
+      const aggregatedCallSignatureToVariable: Record<string, string> = {};
+      const aggregatedReceivingVariableNames: string[] = [];
+      for (const efc of matchingCalls) {
+        if (efc.callSignatureToVariable) {
+          Object.assign(
+            aggregatedCallSignatureToVariable,
+            efc.callSignatureToVariable,
+          );
+        }
+        if (efc.receivingVariableNames) {
+          aggregatedReceivingVariableNames.push(...efc.receivingVariableNames);
+        }
+      }
+
+      // Extract variable names for each call signature using the aggregated map
+      const variableNames: string[] = [];
+      for (const signature of allSignatures) {
+        const variableName = aggregatedCallSignatureToVariable[signature];
+        if (variableName) {
+          variableNames.push(variableName);
+        }
+      }
+
+      // If no variables found via aggregated map, fall back to aggregated receivingVariableNames
+      // This handles cases where receivingVariableNames is set but callSignatureToVariable is not
+      if (
+        variableNames.length === 0 &&
+        aggregatedReceivingVariableNames.length > 0
+      ) {
+        variableNames.push(...aggregatedReceivingVariableNames);
+      }
+
+      if (variableNames.length > 0) {
+        callVariableNames[entityName] = variableNames;
+      }
     }
   }
 
-  return { isolatedDataStructure, functionCalls };
+  return { isolatedDataStructure, functionCalls, callVariableNames };
 }
 
 /**
@@ -326,6 +571,47 @@ function schemaContainsFunctions(schema: Record<string, string>): boolean {
   return false;
 }
 
+/**
+ * Helper: Check if ALL function paths in the schema are jsx-components
+ *
+ * A function path is considered a jsx-component if:
+ * - The value is 'jsx-component', OR
+ * - The functionCallReturnValue for that path is 'jsx-component'
+ *
+ * Returns true if ALL function paths are jsx-components (entity should NOT be mocked)
+ * Returns false if there are any real functions (entity may need mocking)
+ */
+function allFunctionsAreJsxComponents(schema: Record<string, string>): boolean {
+  // Get all function paths (paths ending with () that aren't functionCallReturnValue)
+  const functionPaths = Object.entries(schema ?? {}).filter(([path, value]) => {
+    // Only consider paths that are function calls
+    if (!path.includes('(')) return false;
+    // Skip functionCallReturnValue entries - we check those separately
+    if (path.includes('functionCallReturnValue')) return false;
+    // This is a function call path
+    return value === 'function' || value === 'jsx-component';
+  });
+
+  // If no function paths at all, return false (no functions to check)
+  if (functionPaths.length === 0) return false;
+
+  // Check if ALL function paths are jsx-components
+  for (const [path, value] of functionPaths) {
+    // If the value itself is jsx-component, skip it
+    if (value === 'jsx-component') continue;
+
+    // Check if the functionCallReturnValue for this path is jsx-component
+    const returnValuePath = path + '.functionCallReturnValue';
+    if (schema[returnValuePath] === 'jsx-component') continue;
+
+    // This is a real function that's NOT a jsx-component
+    return false;
+  }
+
+  // All function paths are jsx-components
+  return true;
+}
+
 /**
  * Helper: Check if a return value schema has actual return value data (not just function type markers)
  *
@@ -349,12 +635,80 @@ function hasActualReturnValueData(schema: Record<string, string>): boolean {
   return false;
 }
 
+/**
+ * Helper: Check if a return value schema contains chained method calls (not just simple function calls)
+ *
+ * A chained method call has a pattern like:
+ * - `z.string()` - method call on object z
+ * - `z.string().cuid2()` - chained method calls
+ * - `client.schema().action()` - chained method calls
+ *
+ * A simple function call is just:
+ * - `FileProvider()` - standalone function call (no dot before parens)
+ *
+ * We detect chained calls by looking for patterns where there's a `.` followed by an identifier
+ * and then `()`. The pattern `.identifier()` indicates a method call, not a standalone function.
+ *
+ * EXCEPTION: React Context's .Provider and .Consumer are built-in components that
+ * look like method calls but aren't. When a component uses <SomeContext.Provider>,
+ * the AST creates paths like "SomeContext.Provider()" which should NOT trigger
+ * the chained method call detection.
+ */
+function hasChainedMethodCalls(schema: Record<string, string>): boolean {
+  // Pattern: look for ".identifier(" which indicates a method call
+  // This distinguishes "z.string()" (chained) from "FileProvider()" (simple)
+  const chainedMethodPattern = /\.\w+\(/;
+
+  for (const [path, value] of Object.entries(schema ?? {})) {
+    // Skip JSX components - they look like chained method calls (e.g., Context.Provider())
+    // but they're actually React components used in JSX, not method chains to bypass
+    if (value === 'jsx-component') {
+      continue;
+    }
+
+    // Only look at paths that contain function calls
+    if (path.includes('(') || value === 'function') {
+      if (chainedMethodPattern.test(path)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Validation function name prefixes that should always be mocked.
+ * These functions validate data using schemas (e.g., Zod) that we can't easily
+ * generate data for. Instead of trying to generate data that passes validation,
+ * we mock the validation function itself to return its input unchanged.
+ */
+const VALIDATION_FUNCTION_PREFIXES = ['validate', 'check', 'verify', 'assert'];
+
+/**
+ * Check if a function name indicates it's a validation function that should be mocked.
+ * Validation functions are identified by their name starting with common validation prefixes.
+ */
+export function isValidationFunction(name: string): boolean {
+  const lowerName = name.toLowerCase();
+  return VALIDATION_FUNCTION_PREFIXES.some((prefix) =>
+    lowerName.startsWith(prefix),
+  );
+}
+
 /**
  * Helper: Determine which dependencies should be mocked based on whether they contain functions
  *
  * Only entities that are functions or contain functions in their return values need to be mocked.
  * Data constants (like arrays, objects, strings) don't need mocking because they don't have
  * behavior that needs to be replaced.
+ *
+ * Additionally, validation functions (names starting with validate, check, verify, assert)
+ * are always mocked because they use validation schemas we can't easily generate data for.
+ *
+ * Functions/chains with no return value are also mocked because:
+ * - If a function takes parameters but returns nothing, it's doing side effects (validation, logging)
+ * - If a chain like z.string().cuid2() has no functionCallReturnValue, the chain is doing
+ *   operations (like schema building/validation) whose return is meaningless to us
  */
 export function determineMockedDependencies(entity: Entity) {
   const mockedEntities: { filePath: string; entityName: string }[] = [];
@@ -366,6 +720,7 @@ export function determineMockedDependencies(entity: Entity) {
       const entitySignatureSchema = dataStructure.signatureSchema ?? {};
 
       const emptySignature = Object.keys(entitySignatureSchema).length === 0;
+      const hasSignature = !emptySignature;
       const complexSignature = Object.values(entitySignatureSchema).some(
         (value) => value === 'object' || value === 'array',
       );
@@ -393,11 +748,46 @@ export function determineMockedDependencies(entity: Entity) {
         entityReturnValueSchema ?? {},
       ).some((value) => value === 'object' || value === 'array');
 
+      // 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
+      // e.g., z.string().cuid2() or authenticatedActionClient.schema().action()
+      // These chains are doing operations (validation, schema building) we want to bypass
+      // NOTE: Simple function calls like FileProvider() are NOT chained - only method calls
+      // with a pattern like .method() count as chained
+      const hasChainedCallsWithNoReturn =
+        hasChainedMethodCalls(entityReturnValueSchema) && !hasReturnValue;
+
+      // Check if ALL functions in the return value schema are jsx-components
+      // 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 =
-        (signatureHasFunctions || returnValueHasFunctions) &&
-        hasReturnValue &&
-        ((emptySignature && hasReturnValue) ||
-          (!complexSignature && complexReturnValue));
+        !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 &&
+            !complexSignature &&
+            complexReturnValue));
 
       if (entityShouldBeMocked) {
         mockedEntities.push({
@@ -410,3 +800,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;
+}