@codeyam/codeyam-cli 0.0.0 → 0.1.0-staging.036391e

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

@@ -0,0 +1,758 @@
+import { awsLog, awsLogDebugLevel } from "../../../../../../../packages/utils/index.js";
+import measureAndReportExecutionTime from "../../../utils/measureAndReportExecutionTime.js";
+import { deduplicateFunctionSchemas, detectWrapperRequirements, fillInDirectSchemaGapsAndUnknowns, generateEntityDataStructure, getConditionalUsages, getEquivalentSignatureVariables, getFunctionSignature, getReturnValue, getSourceEquivalencies, getUsageEquivalencies, getConditionalEffects, getCompoundConditionals, getChildBoundaryGatingConditions, getJsxRenderingUsages, } from "../../../../../../../packages/ai/index.js";
+// Set to true to process entities one at a time for easier debugging.
+const DEBUG_SEQUENTIAL_EXECUTION = false;
+// VERSION MARKER: server-only-detection-v2 (2025-12-28)
+// This version includes automatic detection of "use server" and "server-only" files
+// and runs server-only detection even for cached entities
+/**
+ * PHASE 2: Prepare entity data structures
+ * Generate data structures for all entities upfront, before graph traversal.
+ * This ensures that data structure generation failures don't corrupt the traversal state.
+ */
+export default async function prepareEntityDataStructures(allEntities, projectAnalyzer, options) {
+    const processEntity = async (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);
+                if (!fileAnalyzer) {
+                    awsLog(`CodeYam: prepareEntityDataStructures: FileAnalyzer not found`, {
+                        entityFilePath: entity.filePath,
+                        entityName: entity.name,
+                    });
+                    // 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 || (entity.metadata = {});
+                        // Deep clone dependencySchemas to avoid shared references
+                        // We need to clone because getReturnValue() returns direct references to schema objects
+                        // and multiple entities might reference the same dependency
+                        const clonedDependencySchemas = {};
+                        for (const filePath in isolatedDataStructure.dependencySchemas) {
+                            clonedDependencySchemas[filePath] = {};
+                            for (const entityName in isolatedDataStructure.dependencySchemas[filePath]) {
+                                const depSchema = isolatedDataStructure.dependencySchemas[filePath][entityName];
+                                clonedDependencySchemas[filePath][entityName] = {
+                                    signatureSchema: { ...depSchema.signatureSchema },
+                                    returnValueSchema: { ...depSchema.returnValueSchema },
+                                    usageEquivalencies: depSchema.usageEquivalencies,
+                                    sourceEquivalencies: depSchema.sourceEquivalencies,
+                                };
+                            }
+                        }
+                        // LOGGING: Track dependencySchemas entity names for debugging :: format issues
+                        const allEntityNames = [];
+                        for (const filePath in clonedDependencySchemas) {
+                            for (const entityName in clonedDependencySchemas[filePath]) {
+                                allEntityNames.push(`${filePath}:${entityName}`);
+                            }
+                        }
+                        entity.metadata.isolatedDataStructure = {
+                            signatureSchema: deduplicateFunctionSchemas(isolatedDataStructure.signatureSchema),
+                            returnValueSchema: deduplicateFunctionSchemas(isolatedDataStructure.returnValueSchema),
+                            equivalentSignatureVariables: isolatedDataStructure.equivalentSignatureVariables,
+                            dependencySchemas: clonedDependencySchemas,
+                            environmentVariables: isolatedDataStructure.environmentVariables,
+                            // Use enriched conditional usages with source tracing from analysis
+                            conditionalUsages: isolatedDataStructure.conditionalUsages,
+                            // Include conditional effects for execution flow generation
+                            conditionalEffects: isolatedDataStructure.conditionalEffects,
+                            // Include compound conditionals for complete execution flow generation
+                            compoundConditionals: isolatedDataStructure.compoundConditionals,
+                            // Include root entity's equivalencies for merge step
+                            usageEquivalencies: isolatedDataStructure.usageEquivalencies,
+                            sourceEquivalencies: isolatedDataStructure.sourceEquivalencies,
+                            // Include child boundary gating conditions for child component flow merging
+                            childBoundaryGatingConditions: isolatedDataStructure.childBoundaryGatingConditions,
+                            // Include JSX rendering usages for array size and text length flow generation
+                            jsxRenderingUsages: isolatedDataStructure.jsxRenderingUsages,
+                        };
+                        // Detect wrapper requirements (Context providers, etc.)
+                        const wrapperRequirements = detectWrapperRequirements({
+                            entity,
+                            fileAnalyzer,
+                        });
+                        if (wrapperRequirements.length > 0) {
+                            entity.metadata.wrapperRequirements = wrapperRequirements;
+                        }
+                        // Annotate imported exports with function call information
+                        const importedExports = entity.metadata.importedExports ?? [];
+                        for (const importedExport of importedExports) {
+                            const relevantCalls = functionCalls[importedExport.name];
+                            if (relevantCalls) {
+                                importedExport.calls = relevantCalls;
+                            }
+                            const relevantVariableNames = callVariableNames[importedExport.name];
+                            if (relevantVariableNames) {
+                                importedExport.callVariableNames = relevantVariableNames;
+                            }
+                        }
+                        // Annotate node module imports with function call information
+                        for (const [path, infos] of Object.entries(entity.metadata.nodeModuleImports ?? {})) {
+                            for (const info of infos) {
+                                const relevantCalls = functionCalls[info.name];
+                                if (relevantCalls) {
+                                    info.calls = relevantCalls;
+                                }
+                                const relevantVariableNames = callVariableNames[info.name];
+                                if (relevantVariableNames) {
+                                    info.callVariableNames = relevantVariableNames;
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            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;
+                }
+                // Never mock visual components - they render UI and should use real implementation
+                if (importedExport.entityType === 'visual') {
+                    importedExport.isMocked = false;
+                    continue;
+                }
+                // Always mock imports from server-only files ("use server" or import "server-only")
+                // These files contain Server Actions or server-only code that cannot run on the client
+                const importedFilePath = importedExport.resolvedFilePath ?? importedExport.filePath;
+                const importedFileAnalyzer = projectAnalyzer.getFileAnalyzerByPath(importedFilePath);
+                // Use sourceFile.getText() which is always available, unlike file.content which is lazy-loaded
+                const importedFileContent = importedFileAnalyzer?.sourceFile?.getText();
+                const isServerOnly = importedFileContent
+                    ? isServerOnlyFile(importedFileContent)
+                    : false;
+                if (importedFileContent && isServerOnly) {
+                    importedExport.isMocked = true;
+                    continue;
+                }
+                const matchesMockedDep = mockedDependencies.some((dep) => dep.filePath === importedExport.filePath &&
+                    dep.entityName === importedExport.name);
+                importedExport.isMocked = matchesMockedDep;
+            }
+            // Browser globals that should always be mocked (they make network calls)
+            const alwaysMockedBrowserGlobals = ['fetch', 'EventSource'];
+            for (const [path, infos] of Object.entries(entity.metadata?.nodeModuleImports ?? {})) {
+                for (const 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
+        }
+    };
+    const entities = Array.from(allEntities);
+    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 processEntity(entity);
+        }
+    }
+    else {
+        // Parallel execution for speed
+        await Promise.all(entities.map(processEntity));
+    }
+}
+/**
+ * Helper: Generate data structure and extract function call information for an entity
+ */
+async function getEntityDataStructureAndFunctionCalls({ entity, fileAnalyzer, }) {
+    awsLogDebugLevel(1, `Determining data structure for ${entity.name}...`);
+    const { result: dataStructure } = await measureAndReportExecutionTime(() => generateEntityDataStructure({
+        entity,
+        fileAnalyzer,
+    }), `generateEntityDataStructure (${entity.name})`);
+    if (!dataStructure) {
+        return;
+    }
+    awsLogDebugLevel(1, `Data structure complete for ${entity.name}...`);
+    const allDependencies = [
+        ...(entity.metadata?.importedExports ?? []),
+        ...Object.keys(entity.metadata?.nodeModuleImports ?? {}).flatMap((filePath) => entity.metadata?.nodeModuleImports[filePath].map((nmi) => ({
+            filePath,
+            name: nmi.name,
+        })) ?? []),
+    ];
+    // Use helper functions to access SerializableDataStructure
+    // The helper functions handle fuzzy matching and provide the same interface as ScopeDataStructure
+    const dependencySchemas = allDependencies.reduce((acc, importedExport) => {
+        var _a;
+        // Helper functions handle fuzzy name matching internally
+        const signatureSchema = getFunctionSignature(dataStructure, {
+            functionName: importedExport.name,
+        });
+        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 clonedReturnValueSchema = { ...(returnValueSchema ?? {}) };
+        acc[_a = importedExport.filePath] || (acc[_a] = {});
+        acc[importedExport.filePath][importedExport.name] = {
+            signatureSchema: deduplicateFunctionSchemas(clonedSignatureSchema),
+            returnValueSchema: deduplicateFunctionSchemas(clonedReturnValueSchema),
+            usageEquivalencies: getUsageEquivalencies(dataStructure, importedExport.name) ?? {},
+            sourceEquivalencies: getSourceEquivalencies(dataStructure, importedExport.name) ?? {},
+        };
+        // Also create variable-qualified entries to preserve distinct return type schemas
+        // when the same function is called multiple times with different type parameters
+        // (e.g., useFetcher<UserData>() vs useFetcher<ReportData>()).
+        //
+        // Each parameterized call is a SEPARATE entry in externalFunctionCalls, so we need
+        // to iterate over ALL matching calls (not just the first one).
+        const matchingCalls = dataStructure.externalFunctionCalls.filter((fc) => fc.name === importedExport.name ||
+            fc.name.startsWith(importedExport.name + '<'));
+        for (const efc of matchingCalls) {
+            // Check if this call has perVariableSchemas (multiple calls with variable tracking)
+            if (efc?.perVariableSchemas) {
+                // Check if perVariableSchemas has indexed keys (e.g., "fetcher[1]") which indicates
+                // variable reuse with DIFFERENT call signatures (e.g., let fetcher = useFetcher<A>(); fetcher = useFetcher<B>();)
+                // In this case, we need to create SEPARATE entries for each call signature.
+                const perVarKeys = Object.keys(efc.perVariableSchemas);
+                const hasIndexedKeys = perVarKeys.some((key) => /\[\d+\]$/.test(key));
+                if (hasIndexedKeys &&
+                    efc.callSignatureToVariable &&
+                    efc.allCallSignatures) {
+                    // Variable reuse case: create separate entries for each call signature
+                    // Map from call signature to its variable key in perVariableSchemas
+                    // e.g., useFetcher<ConfigData>() -> 'fetcher', useFetcher<SettingsData>() -> 'fetcher[1]'
+                    const varNameCounts = {};
+                    for (const callSig of efc.allCallSignatures) {
+                        const varName = efc.callSignatureToVariable[callSig];
+                        if (!varName)
+                            continue;
+                        // Track occurrence count for this variable name
+                        const occurrence = varNameCounts[varName] ?? 0;
+                        varNameCounts[varName] = occurrence + 1;
+                        // Get the key in perVariableSchemas (indexed if reused)
+                        const perVarKey = occurrence === 0 ? varName : `${varName}[${occurrence}]`;
+                        const varSchema = efc.perVariableSchemas[perVarKey];
+                        if (varSchema && Object.keys(varSchema).length > 0) {
+                            // Create entry with this call signature as the key
+                            const rewrittenSchema = {};
+                            rewrittenSchema[`${callSig}.functionCallReturnValue`] =
+                                'object';
+                            for (const [path, type] of Object.entries(varSchema)) {
+                                const rewrittenPath = path.startsWith(callSig)
+                                    ? path
+                                    : `${callSig}.${path}`;
+                                rewrittenSchema[rewrittenPath] = type;
+                            }
+                            acc[importedExport.filePath][callSig] = {
+                                signatureSchema: deduplicateFunctionSchemas({
+                                    ...signatureSchema,
+                                }),
+                                returnValueSchema: deduplicateFunctionSchemas(rewrittenSchema),
+                                usageEquivalencies: getUsageEquivalencies(dataStructure, importedExport.name) ??
+                                    {},
+                                sourceEquivalencies: getSourceEquivalencies(dataStructure, importedExport.name) ?? {},
+                            };
+                        }
+                    }
+                }
+                else {
+                    // Destructuring case: const { a, b, c } = useLoaderData()
+                    // Merge all variable schemas into a single entry with the call signature as key
+                    const callSignatureKey = efc.callSignature;
+                    // Merge all variable schemas by prepending the call signature to each path.
+                    // perVariableSchemas paths are like "functionCallReturnValue.entities.sha"
+                    // We need to prefix them with the call signature to get:
+                    // "useLoaderData<typeof loader>().functionCallReturnValue.entities.sha"
+                    const mergedReturnValueSchema = {};
+                    // Set the top-level return value as object since it contains named properties
+                    mergedReturnValueSchema[`${callSignatureKey}.functionCallReturnValue`] = 'object';
+                    for (const [varName, perVarSchema] of Object.entries(efc.perVariableSchemas)) {
+                        for (const [path, type] of Object.entries(perVarSchema)) {
+                            // Only prepend the call signature if the path doesn't already have it.
+                            // perVariableSchemas paths may already include the call signature prefix
+                            // (e.g., "useCustomSizes(projectSlug).functionCallReturnValue.customSizes")
+                            // depending on how they were built. If so, use the path as-is.
+                            const rewrittenPath = path.startsWith(callSignatureKey)
+                                ? path
+                                : `${callSignatureKey}.${path}`;
+                            mergedReturnValueSchema[rewrittenPath] = type;
+                        }
+                    }
+                    acc[importedExport.filePath][callSignatureKey] = {
+                        signatureSchema: deduplicateFunctionSchemas({
+                            ...signatureSchema,
+                        }),
+                        returnValueSchema: deduplicateFunctionSchemas(mergedReturnValueSchema),
+                        usageEquivalencies: getUsageEquivalencies(dataStructure, importedExport.name) ?? {},
+                        sourceEquivalencies: getSourceEquivalencies(dataStructure, importedExport.name) ??
+                            {},
+                    };
+                }
+            }
+            else if (efc?.receivingVariableNames?.length === 1) {
+                // For parameterized calls like useFetcher<UserData>(), each is a separate entry
+                // with a single receivingVariableName. Use the call signature as the key.
+                const varName = efc.receivingVariableNames[0];
+                // Use the call signature as the key (e.g., "useFetcher<UserData>()")
+                const callSignatureKey = efc.callSignature;
+                // PREFER perVariableSchemas over getReturnValue() when available
+                // perVariableSchemas has the SPECIFIC schema for this parameterized call,
+                // while getReturnValue() may return merged schemas from multiple calls
+                let parameterizedReturnValue = null;
+                if (efc.perVariableSchemas && efc.perVariableSchemas[varName]) {
+                    // Use the specific schema from perVariableSchemas
+                    parameterizedReturnValue = efc.perVariableSchemas[varName] ?? null;
+                }
+                // Fallback to getReturnValue if perCallSignatureSchemas not available
+                if (!parameterizedReturnValue) {
+                    parameterizedReturnValue = getReturnValue(dataStructure, {
+                        functionName: efc.name, // Use the full parameterized name
+                    });
+                }
+                if (parameterizedReturnValue &&
+                    Object.keys(parameterizedReturnValue).length > 0) {
+                    acc[importedExport.filePath][callSignatureKey] = {
+                        signatureSchema: deduplicateFunctionSchemas({
+                            ...signatureSchema,
+                        }),
+                        returnValueSchema: deduplicateFunctionSchemas({
+                            ...parameterizedReturnValue,
+                        }),
+                        usageEquivalencies: getUsageEquivalencies(dataStructure, importedExport.name) ?? {},
+                        sourceEquivalencies: getSourceEquivalencies(dataStructure, importedExport.name) ??
+                            {},
+                    };
+                }
+            }
+        }
+        return acc;
+    }, {});
+    // Add same-file child components to dependencySchemas.
+    // Same-file components (e.g., AgentCard defined in the same file as AgentTranscriptsPage)
+    // appear in externalFunctionCalls and functionResults but NOT in importedExports or
+    // nodeModuleImports. Without this, their signatures are missing from dependencySchemas
+    // and enrichArrayTypesFromChildSignatures can't find child component field accesses.
+    const allDependencyNames = new Set(allDependencies.map((d) => d.name));
+    for (const efc of dataStructure.externalFunctionCalls) {
+        // Skip if already covered by importedExports or nodeModuleImports
+        if (allDependencyNames.has(efc.name))
+            continue;
+        const signatureSchema = getFunctionSignature(dataStructure, {
+            functionName: efc.name,
+        });
+        const returnValueSchema = getReturnValue(dataStructure, {
+            functionName: efc.name,
+        });
+        // Only add if we have signature or return value data
+        if (!signatureSchema && !returnValueSchema)
+            continue;
+        const clonedSignatureSchema = { ...(signatureSchema ?? {}) };
+        const clonedReturnValueSchema = { ...(returnValueSchema ?? {}) };
+        const entityFilePath = entity.filePath;
+        dependencySchemas[entityFilePath] || (dependencySchemas[entityFilePath] = {});
+        dependencySchemas[entityFilePath][efc.name] = {
+            signatureSchema: deduplicateFunctionSchemas(clonedSignatureSchema),
+            returnValueSchema: deduplicateFunctionSchemas(clonedReturnValueSchema),
+            usageEquivalencies: getUsageEquivalencies(dataStructure, efc.name) ?? {},
+            sourceEquivalencies: getSourceEquivalencies(dataStructure, efc.name) ?? {},
+        };
+    }
+    const rawReturnValue = getReturnValue(dataStructure, { fillInUnknowns: false }) ?? {};
+    // Clone root function schemas before deduplication to avoid mutating shared references
+    const rawSignature = getFunctionSignature(dataStructure, { fillInUnknowns: false }) ?? {};
+    const clonedRawSignature = { ...rawSignature };
+    const clonedRawReturnValue = { ...rawReturnValue };
+    // Get enriched conditional usages with source tracing
+    const conditionalUsages = getConditionalUsages(dataStructure);
+    // Get conditional effects (setter calls inside conditionals)
+    const conditionalEffects = getConditionalEffects(dataStructure);
+    // Get compound conditionals (grouped conditions that must all be true)
+    const compoundConditionals = getCompoundConditionals(dataStructure);
+    const rawUsageEquivalencies = getUsageEquivalencies(dataStructure);
+    const rawSourceEquivalencies = getSourceEquivalencies(dataStructure);
+    // Get child boundary gating conditions for child component flow merging
+    const childBoundaryGatingConditions = getChildBoundaryGatingConditions(dataStructure);
+    // Get JSX rendering usages for array size and text length flow generation
+    const jsxRenderingUsages = getJsxRenderingUsages(dataStructure);
+    const equivalentSignatureVariables = getEquivalentSignatureVariables(dataStructure);
+    const isolatedDataStructure = {
+        signatureSchema: deduplicateFunctionSchemas(clonedRawSignature),
+        returnValueSchema: deduplicateFunctionSchemas(clonedRawReturnValue),
+        equivalentSignatureVariables,
+        dependencySchemas,
+        environmentVariables: dataStructure.environmentVariables,
+        conditionalUsages: Object.keys(conditionalUsages).length > 0 ? conditionalUsages : undefined,
+        // Include conditional effects for execution flow generation
+        conditionalEffects: conditionalEffects.length > 0 ? conditionalEffects : undefined,
+        // Include compound conditionals for complete execution flow generation
+        // These capture grouped conditions like (a || b) && !c && !d
+        compoundConditionals: compoundConditionals.length > 0 ? compoundConditionals : undefined,
+        // Include root entity's equivalencies so they can be used during merge.
+        // These show how the parent's data flows to/from child components.
+        // E.g., for SurveysList, usageEquivalencies shows surveys[] → SurveyCard().signature[0].survey
+        usageEquivalencies: rawUsageEquivalencies ?? {},
+        sourceEquivalencies: rawSourceEquivalencies ?? {},
+        // Include child boundary gating conditions for child component flow merging
+        // Maps child component names to the conditions that must be true for them to render
+        childBoundaryGatingConditions: Object.keys(childBoundaryGatingConditions).length > 0
+            ? childBoundaryGatingConditions
+            : undefined,
+        // Include JSX rendering usages for array size and text length flow generation
+        // These track arrays rendered via .map() and strings interpolated in JSX
+        jsxRenderingUsages: jsxRenderingUsages.length > 0 ? jsxRenderingUsages : undefined,
+    };
+    const functionCalls = {};
+    const callVariableNames = {};
+    // Note: externalFunctionCalls is needed for callSignature info, which isn't exposed through helpers
+    for (const filePath in dependencySchemas) {
+        for (const entityName in dependencySchemas[filePath]) {
+            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, callVariableNames };
+}
+/**
+ * Helper: Check if a schema contains actual function calls
+ * Functions are identified by:
+ * - Paths containing "()" - indicates a function call
+ * - Values equal to "function" - indicates the type is a function
+ */
+function schemaContainsFunctions(schema) {
+    for (const [path, value] of Object.entries(schema ?? {})) {
+        if (path.includes('(') || value === 'function') {
+            return true;
+        }
+    }
+    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)
+ *
+ * A schema entry like `EntityName(): "function"` just indicates the entity is callable.
+ * This is NOT actual return value data - it's a type marker added by getReturnValue() to
+ * indicate the entity is a function.
+ *
+ * Actual return value data would contain paths with `functionCallReturnValue` like:
+ * - `EntityName().functionCallReturnValue`: "object"
+ * - `EntityName().functionCallReturnValue.data`: "array"
+ *
+ * Or for chained calls:
+ * - `supabase.from('table').select('*').functionCallReturnValue`: "array"
+ */
+function hasActualReturnValueData(schema) {
+    for (const path of Object.keys(schema ?? {})) {
+        if (path.includes('functionCallReturnValue')) {
+            return true;
+        }
+    }
+    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 = [];
+    const dependencySchemas = entity.metadata.isolatedDataStructure?.dependencySchemas ?? {};
+    for (const filePath in dependencySchemas) {
+        for (const entityName in dependencySchemas[filePath]) {
+            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({
+                scopeName: entity.name,
+                schema: { ...dataStructure.returnValueSchema },
+            });
+            // Only mock if the entity is a function or contains functions
+            // Data constants (arrays, objects, etc.) don't need mocking
+            const signatureHasFunctions = schemaContainsFunctions(entitySignatureSchema);
+            const returnValueHasFunctions = schemaContainsFunctions(entityReturnValueSchema);
+            // Check for actual return value data (not just function type markers like "EntityName(): function")
+            // 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);
+            // Check for complex return types (object/array), accounting for nullable types
+            // e.g., 'object', 'object | null', 'array | undefined' should all count as complex.
+            // Also detect when functionCallReturnValue has nested child properties — this
+            // proves it's a structured type even if its declared type is still 'unknown'.
+            const returnValueKeys = Object.keys(entityReturnValueSchema ?? {});
+            const complexReturnValue = Object.values(entityReturnValueSchema ?? {}).some((value) => {
+                const baseType = value?.split(' | ')[0];
+                return baseType === 'object' || baseType === 'array';
+            }) ||
+                returnValueKeys.some((key) => key.includes('functionCallReturnValue.') ||
+                    key.includes('functionCallReturnValue['));
+            // Check if this is a validation function that should always be mocked
+            const isValidationFn = isValidationFunction(entityName);
+            // Check if entity has chained method calls but no return value
+            // 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,
+                    entityName,
+                });
+            }
+        }
+    }
+    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