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

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

@@ -1,6 +1,9 @@
 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";
+// 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.
@@ -9,105 +12,167 @@ import { fillInDirectSchemaGapsAndUnknowns, generateEntityDataStructure, dedupli
 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)
+        // 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 } = 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,
-                    };
+                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 || (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 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;
+                        }
+                        // 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;
+                                }
+                            }
+                        }
+                    }
                 }
             }
-            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;
+            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 ?? {})) {
+            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 + '::')));
                         }
                     }
                 }
@@ -147,17 +212,19 @@ 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, 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[_a = importedExport.filePath] || (acc[_a] = {});
         acc[importedExport.filePath][importedExport.name] = {
@@ -166,6 +233,83 @@ 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 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 = {};
+                // 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 = 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;
     }, {});
     const rawReturnValue = getReturnValue(dataStructure, { fillInUnknowns: false }) ?? {};
@@ -175,6 +319,8 @@ async function getEntityDataStructureAndFunctionCalls({ entity, fileAnalyzer, })
     const clonedRawReturnValue = { ...rawReturnValue };
     // 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),
@@ -182,17 +328,62 @@ async function getEntityDataStructureAndFunctionCalls({ entity, fileAnalyzer, })
         dependencySchemas,
         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 = {};
+    const callVariableNames = {};
     // 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 = [];
+            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 = {};
+            const aggregatedReceivingVariableNames = [];
+            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 = [];
+            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 };
 }
 /**
  * Helper: Check if a schema contains actual function calls
@@ -208,6 +399,46 @@ function schemaContainsFunctions(schema) {
     }
     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) {
+    // 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)
  *
@@ -230,12 +461,73 @@ function hasActualReturnValueData(schema) {
     }
     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) {
+    // 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) {
+    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) {
     const mockedEntities = [];
@@ -245,6 +537,7 @@ export function determineMockedDependencies(entity) {
             const dataStructure = dependencySchemas[filePath][entityName];
             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');
             // Clone before passing to fillInDirectSchemaGapsAndUnknowns because it mutates its input
             const entityReturnValueSchema = fillInDirectSchemaGapsAndUnknowns({
@@ -260,10 +553,37 @@ export function determineMockedDependencies(entity) {
             // 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');
-            const entityShouldBeMocked = (signatureHasFunctions || returnValueHasFunctions) &&
-                hasReturnValue &&
-                ((emptySignature && hasReturnValue) ||
-                    (!complexSignature && complexReturnValue));
+            // 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 = !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({
                     filePath,
@@ -274,4 +594,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