@codeyam/codeyam-cli 0.1.0-staging.09652b8 → 0.1.0-staging.28f73cf

package/analyzer-template/project/writeScenarioComponents.ts

@@ -43,6 +43,12 @@ interface WriteScenarioComponentsArgs {
   })[];
   writtenScenarioComponents?: { [key: string]: string[] };
   fileStore?: LazyFileStore;
+  /**
+   * When a default export needs to be accessible as a named export (e.g., when
+   * the parent imports it as `{ Name }` via an index re-export), pass the name here.
+   * A re-export statement `export { default as Name };` will be added to the output.
+   */
+  exportAsNamed?: string;
 }
 
 type EnhancedImportedExport = Omit<
@@ -417,6 +423,7 @@ export default async function writeScenarioComponents({
   namespaceMocks,
   writtenScenarioComponents = {},
   fileStore,
+  exportAsNamed,
 }: WriteScenarioComponentsArgs): Promise<{
   scenarioComponentPaths: string[];
   writtenScenarioComponents: { [key: string]: string[] };
@@ -651,10 +658,12 @@ export default async function writeScenarioComponents({
     (importedExportEntity as Entity).localFilePath = importedExport.filePath;
 
     if (!importedExport.isMocked) {
+      // Use resolvedFilePath (actual entity location) for scenario component writing.
+      // This is critical for re-exports: when importing from index.tsx which re-exports
+      // from a nested file, we need to write scenario components for the actual file
+      // where the entity code lives, not the re-export file.
       const importedExportFilePath =
-        importedExportEntity.localFilePath === file.path
-          ? (importedExport.resolvedFilePath ?? importedExport.filePath)
-          : importedExport.filePath;
+        importedExport.resolvedFilePath ?? importedExport.filePath;
 
       if (importedExportFilePath !== file.path) {
         if (
@@ -676,17 +685,41 @@ export default async function writeScenarioComponents({
             ? fileStore.getByPath(importedExportFilePath)
             : project.files.find((f) => f.path === importedExportFilePath);
 
+          // Fallback: if file at resolvedFilePath doesn't exist, try filePath
+          // This handles cases where the actual entity file isn't in project.files
+          // (e.g., type re-exports where only the index file is tracked)
+          if (
+            !fileNotMocked &&
+            importedExport.resolvedFilePath &&
+            importedExport.filePath !== importedExport.resolvedFilePath
+          ) {
+            const fallbackPath = importedExport.filePath;
+            fileNotMocked = fileStore
+              ? fileStore.getByPath(fallbackPath)
+              : project.files.find((f) => f.path === fallbackPath);
+          }
+
+          // Skip if file still not found - can't write scenario component without the file
+          if (!fileNotMocked) {
+            continue;
+          }
+
           // Ensure content is loaded for the file
           if (
             fileNotMocked &&
             fileStore &&
-            !fileStore.isContentLoaded(importedExportFilePath)
+            !fileStore.isContentLoaded(fileNotMocked.path)
           ) {
-            fileNotMocked = await fileStore.ensureContent(
-              importedExportFilePath,
-            );
+            fileNotMocked = await fileStore.ensureContent(fileNotMocked.path);
           }
 
+          // When a default export is imported as named (via index re-export), we need
+          // to add a named re-export to the scenario component so the import works.
+          // e.g., if file has `export default X` but parent does `import { X } from '...'`
+          const needsNamedReExport =
+            importedExport.resolvedIsDefault === true &&
+            importedExport.isDefault === false;
+
           const {
             scenarioComponentPaths: newScenarioComponentPaths,
             writtenScenarioComponents: updatedWrittenScenarioComponents,
@@ -704,6 +737,8 @@ export default async function writeScenarioComponents({
             namespaceMocks,
             writtenScenarioComponents,
             fileStore,
+            // Pass the import name so we can add `export { default as Name };`
+            exportAsNamed: needsNamedReExport ? importedExport.name : undefined,
           });
           writtenScenarioComponents = updatedWrittenScenarioComponents;
           scenarioComponentPaths.push(...newScenarioComponentPaths);
@@ -737,18 +772,38 @@ export default async function writeScenarioComponents({
             relativeMocksDir,
             scenario.name,
           );
+        } else if (importedExport.isMocked) {
+          // No mock structure available, but isMocked is true.
+          // Generate a simple stub mock that returns scenario data.
+          // This prevents ReferenceError at runtime when the stripped
+          // function is called (e.g., local helper functions like getInitialProps).
+          const functionName = importedExport.name;
+
+          // Add scenarios import if not present
+          if (fileContent.indexOf('import { scenarios } from') === -1) {
+            const mockDataPath = `${relativeMocksDir}/MockData_${safeFileName(scenario.name)}`;
+            const importStatement = `import { scenarios } from "${mockDataPath}";`;
+            fileContent = `${fileContent}\n\n\n${importStatement}`;
+          }
+
+          // Generate a simple stub that returns the scenario data for this function
+          const stubMock = `\n\n// Stub mock for local function without mock structure\nfunction ${functionName}(...args) {\n  return scenarios().data()?.["${functionName}()"];\n}`;
+          fileContent += stubMock;
         }
       }
     }
 
     // Try to find the import mapping using different key formats
     // The import mapping may use either absolute or relative paths as keys
-    // IMPORTANT: Use filePath (where it's imported FROM), not resolvedFilePath (where entity lives)
-    // For re-exports like ~codeyam/types, filePath="packages/types/index.ts",
-    // resolvedFilePath="packages/types/src/types/Commit.ts"
-    // We need to generate files at the import location (index.ts), not the entity location
+    // Use filePath (import source) for looking up the import mapping
+    // because that's how imports are written in source code
     const mockFilePathRelative = importedExport.filePath;
 
+    // For scenario component paths, prefer resolvedFilePath (where entity actually lives)
+    // because that's where scenario component files are written
+    const scenarioFilePathRelative =
+      importedExport.resolvedFilePath ?? importedExport.filePath;
+
     // Try looking up with different key formats (absolute, relative, resolved absolute)
     // Filter out undefined keys to avoid misleading undefined lookups
     const lookupKeys = [
@@ -802,10 +857,28 @@ export default async function writeScenarioComponents({
     } else {
       // For non-mocked imports, rewrite the import path to point to the generated scenario file
       // Use fileStore for O(1) lookup when available
-      const fileNotMocked = fileStore
-        ? fileStore.getByPath(mockFilePathRelative)
-        : project.files.find((f) => f.path === mockFilePathRelative);
-      const fileName = mockFilePathRelative.split('/').pop();
+      // First try resolvedFilePath (where entity lives), fallback to filePath (import source)
+      let fileNotMocked = fileStore
+        ? fileStore.getByPath(scenarioFilePathRelative)
+        : project.files.find((f) => f.path === scenarioFilePathRelative);
+
+      // Track which path we're actually using for the scenario component
+      let actualScenarioFilePathRelative = scenarioFilePathRelative;
+      if (
+        !fileNotMocked &&
+        importedExport.resolvedFilePath &&
+        importedExport.filePath !== importedExport.resolvedFilePath
+      ) {
+        // Fallback to filePath if file at resolvedFilePath doesn't exist
+        actualScenarioFilePathRelative = importedExport.filePath;
+        fileNotMocked = fileStore
+          ? fileStore.getByPath(actualScenarioFilePathRelative)
+          : project.files.find(
+              (f) => f.path === actualScenarioFilePathRelative,
+            );
+      }
+
+      const fileName = actualScenarioFilePathRelative.split('/').pop();
       const fileNotMockedIsIndex = isIndexPath(fileNotMocked?.path);
       const mockFilePath = isFrameworkRoute(
         fileNotMocked,
@@ -818,7 +891,7 @@ export default async function writeScenarioComponents({
             rootFile,
             entity: importedExportEntity,
             rootAnalysis,
-            scenarioComponentPath: mockFilePathRelative,
+            scenarioComponentPath: actualScenarioFilePathRelative,
             project,
             framework,
             scenario,
@@ -826,7 +899,7 @@ export default async function writeScenarioComponents({
             .split('.')
             .slice(0, -1)
             .join('.')
-        : mockFilePathRelative.replace(
+        : actualScenarioFilePathRelative.replace(
             `${fileName}`,
             `${importedExportEntity.sha}_${fileNotMockedIsIndex ? 'index_' : ''}${safeFileName(importedExportEntity.name)}_${safeFileName(scenario.name)}`,
           );
@@ -841,7 +914,39 @@ export default async function writeScenarioComponents({
           'g',
         );
 
-        fileContent = fileContent.replace(importRegExp, `${path}$1`);
+        // Check if the original import path still exists in the file
+        // If it was already rewritten by another entity from the same module,
+        // we need to add a separate import statement for this entity
+        if (fileContent.match(importRegExp)) {
+          fileContent = fileContent.replace(importRegExp, `${path}$1`);
+        } else {
+          // The import path was already rewritten - add a new import for this entity
+          // This handles cases where multiple entities are imported from the same index file
+          // (e.g., import { A, B, C } from '@pkg') and each has its own scenario file
+          const entityImportName = importedExport.name;
+          const newImport = `import { ${entityImportName} } from '${path}';`;
+
+          // First, try to remove this entity from the already-rewritten grouped import
+          // This prevents duplicate/conflicting imports
+          // Match patterns like "EntityName," or ", EntityName" or "EntityName" (if only one)
+          const removeFromGroupedImportPatterns = [
+            new RegExp(`\\b${entityImportName}\\s*,\\s*`, 'g'), // "EntityName, "
+            new RegExp(`\\s*,\\s*${entityImportName}\\b`, 'g'), // ", EntityName"
+          ];
+          for (const pattern of removeFromGroupedImportPatterns) {
+            fileContent = fileContent.replace(pattern, '');
+          }
+
+          // Add the new import at the beginning of fileContent
+          // Note: The header comment (// Scenario:) doesn't exist yet - it's prepended at writeFile time
+          // So prepending here puts the import right after the header in the final output
+          //
+          // IMPORTANT: We cannot use indexOf('// Scenario:') + '\n\n' here because:
+          // 1. The header doesn't exist during processing
+          // 2. indexOf would return -1, and indexOf('\n\n', -1) starts from 0
+          // 3. This could find a \n\n inside a function body, inserting the import there!
+          fileContent = newImport + '\n' + fileContent;
+        }
       }
     }
   }
@@ -860,6 +965,36 @@ export default async function writeScenarioComponents({
     );
   }
 
+  // Rewrite node_module imports that have universal mocks
+  // Universal mocks create mock files at __codeyamMocks__/{safeFileName}.tsx
+  // We need to rewrite imports like `import { logger } from "@formbricks/logger"`
+  // to `import { logger } from "../__codeyamMocks__/_formbricks_logger"`
+  const universalMocks = project.metadata?.universalMocks ?? [];
+  const nodeModuleUniversalMocks = universalMocks.filter(
+    (mock) => mock.nodeModule && mock.content,
+  );
+
+  for (const universalMock of nodeModuleUniversalMocks) {
+    const originalPath = universalMock.filePath;
+    // Create the mock file name using the same pattern as applyUniversalMocks
+    const safeFileName = originalPath.replace(/[^a-zA-Z0-9_\-./]/g, '_');
+    const mockFileRelativePath = `${relativeMocksDir}/${safeFileName}`;
+
+    // Match both single and double quotes, and handle both named and default imports
+    // Pattern 1: import { x, y } from "module"
+    // Pattern 2: import x from "module"
+    // Pattern 3: import * as x from "module"
+    const importRegex = new RegExp(
+      `(import\\s+(?:\\{[^}]*\\}|\\*\\s+as\\s+\\w+|\\w+)\\s+from\\s+)['"]${originalPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}['"]`,
+      'g',
+    );
+
+    fileContent = fileContent.replace(
+      importRegex,
+      `$1'${mockFileRelativePath}'`,
+    );
+  }
+
   if (
     rootAnalysis.entitySha === entity.sha &&
     entity.metadata?.notExported &&
@@ -872,6 +1007,17 @@ export default async function writeScenarioComponents({
     }
   }
 
+  // When a default export is imported as named via re-export (e.g., index.tsx re-exports
+  // a default export as named), we need to add a named export so the parent's
+  // import statement works: `import { Name } from './path'`
+  // The local variable name is the same as exportAsNamed (e.g., ScenarioEditor)
+  if (exportAsNamed) {
+    const namedExport = `export { ${exportAsNamed} };`;
+    if (!fileContent.includes(namedExport)) {
+      fileContent = `${fileContent}\n\n${namedExport}`;
+    }
+  }
+
   const basePath = safeFolder(file.path.split('/').slice(0, -1).join('/'));
   const extension = file.name.split('.').pop();
   // Include scenario name in path to allow multiple scenarios to coexist

package/analyzer-template/project/writeUniversalMocks.ts

@@ -28,7 +28,26 @@ export default async function writeUniversalMocks({
 }: WriteUniversalMocksArgs) {
   const { project } = projectAnalyzer;
 
-  for (const universalMock of project.metadata?.universalMocks ?? []) {
+  // Group node_module mocks by filePath to merge multiple exports into one file
+  // This prevents later mocks from overwriting earlier ones for the same package
+  const nodeModuleMocksByPath = new Map<
+    string,
+    Array<(typeof universalMocks)[number]>
+  >();
+  const universalMocks = project.metadata?.universalMocks ?? [];
+
+  for (const mock of universalMocks) {
+    if (mock.nodeModule) {
+      const existing = nodeModuleMocksByPath.get(mock.filePath) ?? [];
+      existing.push(mock);
+      nodeModuleMocksByPath.set(mock.filePath, existing);
+    }
+  }
+
+  // Track which filePaths we've already processed (for node_modules)
+  const processedNodeModulePaths = new Set<string>();
+
+  for (const universalMock of universalMocks) {
     console.log(
       'CodeYam: Initializing universal mock',
       universalMock.filePath,
@@ -71,6 +90,16 @@ export default async function writeUniversalMocks({
           mockContent = file.content.replace(entityCode, universalMock.content);
         }
       } else {
+        // For node_modules, check if we've already processed this path
+        // (multiple mocks for the same package should be merged)
+        if (universalMock.nodeModule) {
+          if (processedNodeModulePaths.has(universalMock.filePath)) {
+            // Already processed as part of a merged mock, skip
+            continue;
+          }
+          processedNodeModulePaths.add(universalMock.filePath);
+        }
+
         const appPath = getAppPath(
           project,
           framework,
@@ -87,14 +116,37 @@ export default async function writeUniversalMocks({
           CODEYAM_MOCKS_DIRNAME,
           safeFileName(filePathForMockFile) + '.tsx',
         );
-        const exportName =
-          universalMock.entityName === 'default'
-            ? 'default'
-            : `{ ${universalMock.entityName} }`;
-        if (exportName === 'default') {
-          mockContent = `export default ${universalMock.content}`;
+
+        // For node_modules, merge all mocks for this filePath
+        const mocksToProcess = universalMock.nodeModule
+          ? (nodeModuleMocksByPath.get(universalMock.filePath) ?? [
+              universalMock,
+            ])
+          : [universalMock];
+
+        const contentParts: string[] = [];
+        const namedExports: string[] = [];
+        let hasDefaultExport = false;
+
+        for (const mock of mocksToProcess) {
+          if (mock.entityName === 'default') {
+            hasDefaultExport = true;
+            contentParts.push(`export default ${mock.content}`);
+          } else {
+            contentParts.push(mock.content);
+            namedExports.push(mock.entityName);
+          }
+        }
+
+        // Build the final mock content
+        if (namedExports.length > 0) {
+          mockContent = contentParts.join('\n\n');
+          // Only add export statement for non-default exports if not already in content
+          if (!hasDefaultExport || namedExports.length > 0) {
+            mockContent += `\n\nexport { ${namedExports.join(', ')} };`;
+          }
         } else {
-          mockContent = `${universalMock.content}\n\nexport { ${universalMock.entityName} };`;
+          mockContent = contentParts.join('\n\n');
         }
       }
 
@@ -136,6 +188,12 @@ export default async function writeUniversalMocks({
         );
         const allSourceFiles = projectAnalyzer.getAllSourceFiles();
         for (const sourceFile of allSourceFiles) {
+          // Skip JSON files - they should not have imports rewritten
+          // This can happen when resolveJsonModule is enabled in tsconfig
+          // and package.json is included in the TypeScript program
+          if (sourceFile.path.endsWith('.json')) {
+            continue;
+          }
           if (importRegEx.test(sourceFile.content)) {
             const relativeMockPath = getRelativePath(sourceFile.path, mockPath);
             const newContent = sourceFile.content.replace(

package/background/src/lib/virtualized/project/constructMockCode.js

@@ -187,7 +187,13 @@ export default function constructMockCode(mockName, dependencySchemas) {
                 return [];
             }
             const addReturnValueFunctionAccessor = (dataPath) => {
-                if (returnValue.returnsFunctionArgs) {
+                // Add function call accessor if:
+                // - There are actual arguments, OR
+                // - This is a callable (not a method that returns an array directly)
+                // For methods like getAll() that return arrays, the data is at ["getAll()"] not ["getAll()"]["()"]
+                if (returnValue.returnsFunctionArgs &&
+                    (returnValue.returnsFunctionArgs.length > 0 ||
+                        !returnValue.returnsFunctionArray)) {
                     if (returnValue.isArray) {
                         dataPath = `${dataPath}${optionalAccess('[0]')}`;
                     }
@@ -214,14 +220,57 @@ export default function constructMockCode(mockName, dependencySchemas) {
                 .filter(Boolean);
         };
         const constructContent = (dataPaths) => {
-            const { name, args, nested, isArray, isGenericArray, returnsFunctionArgs, returnsFunctionArray, isAsyncFunction, } = returnValue;
+            const { name, args, nested, isArray, isGenericArray, returnsFunctionArgs, returnsFunctionArray, isAsyncFunction, hasNoReturnData, } = returnValue;
             const nestedContent = (nested ?? []).map((nestedItem) => {
                 const nestedContent = constructReturnValueString(nestedItem, dataPaths);
                 return nestedContent;
             });
+            // Array prototype methods that should be ignored when building mocks
+            // (these work on any array - we don't need to mock them)
+            const ARRAY_PROTOTYPE_METHODS = new Set([
+                'at',
+                'concat',
+                'copyWithin',
+                'entries',
+                'every',
+                'fill',
+                'filter',
+                'find',
+                'findIndex',
+                'findLast',
+                'findLastIndex',
+                'flat',
+                'flatMap',
+                'forEach',
+                'includes',
+                'indexOf',
+                'join',
+                'keys',
+                'lastIndexOf',
+                'map',
+                'pop',
+                'push',
+                'reduce',
+                'reduceRight',
+                'reverse',
+                'shift',
+                'slice',
+                'some',
+                'sort',
+                'splice',
+                'toLocaleString',
+                'toReversed',
+                'toSorted',
+                'toSpliced',
+                'toString',
+                'unshift',
+                'values',
+                'with',
+                'length',
+            ]);
             const levelContentItems = [];
             // Add spread for data paths when:
-            // - Not a function returning an array
+            // - Not a function returning an array, OR function returns array with custom methods
             // - Has function args OR not an array
             // - Not structural, OR is a structural [0] element with nested content
             //   (array elements with nested functions need their other properties spread)
@@ -229,7 +278,19 @@ export default function constructMockCode(mockName, dependencySchemas) {
                 returnValue.name === '[0]' &&
                 nested &&
                 nested.length > 0;
-            if (!returnsFunctionArray &&
+            // Check if function returns array but has custom methods (not just array prototype methods)
+            // Excludes array indices like [0], [1], [] which are not methods
+            const hasCustomMethodsOnArrayReturn = returnsFunctionArray &&
+                nested &&
+                nested.length > 0 &&
+                nested.some((n) => {
+                    // Skip array indices - they're not methods
+                    if (n.name.match(/^\[\d*\]$/))
+                        return false;
+                    const methodName = n.name.replace(/[<(].*$/, '');
+                    return !ARRAY_PROTOTYPE_METHODS.has(methodName);
+                });
+            if ((!returnsFunctionArray || hasCustomMethodsOnArrayReturn) &&
                 (returnsFunctionArgs || !isArray) &&
                 (!returnValue.isStructural || isStructuralArrayElementWithNested)) {
                 levelContentItems.push(...dataPaths.map((path) => `...${path}`));
@@ -242,7 +303,16 @@ export default function constructMockCode(mockName, dependencySchemas) {
                     .join(', ');
                 let funcContents = '';
                 if (returnsFunctionArray) {
-                    if (levelContents.length === 0) {
+                    if (hasNoReturnData) {
+                        // Function has no return data (only signatures) - return empty array
+                        funcContents = 'return []';
+                    }
+                    else if (levelContents.length === 0 && dataPaths.length === 1) {
+                        // When returning an array with no nested content, return the data path directly
+                        // (the data path points to the array in scenario data)
+                        funcContents = `return ${dataPaths[0]}`;
+                    }
+                    else if (levelContents.length === 0) {
                         funcContents = 'return []';
                     }
                     else {
@@ -250,8 +320,19 @@ export default function constructMockCode(mockName, dependencySchemas) {
                     }
                 }
                 else {
+                    // Check if function has no actual return data (only signatures)
+                    const hasNestedItems = nested && nested.length > 0;
+                    const hasActualNestedContent = nestedContent.filter(Boolean).length > 0;
                     if (levelContentItems.length === 1 && dataPaths.length === 1) {
-                        funcContents = `return ${dataPaths[0]}`;
+                        if (hasNoReturnData ||
+                            (hasNestedItems && !hasActualNestedContent)) {
+                            // Function has no return data (only signatures) - return empty array
+                            funcContents = 'return []';
+                        }
+                        else {
+                            // Has return data - return data path
+                            funcContents = `return ${dataPaths[0]}`;
+                        }
                     }
                     else {
                         funcContents = `return {\n${indent(levelContents)}\n}`;
@@ -262,12 +343,30 @@ export default function constructMockCode(mockName, dependencySchemas) {
                     return levelContents;
                 }
             }
+            // Check if all nested items are array prototype methods
+            const hasOnlyArrayPrototypeMethods = returnsFunctionArray &&
+                nested &&
+                nested.length > 0 &&
+                nested.every((n) => {
+                    // Extract method name before type params and args (e.g., "reduce<...>(...)" -> "reduce")
+                    const methodName = n.name.replace(/[<(].*$/, '');
+                    return ARRAY_PROTOTYPE_METHODS.has(methodName);
+                });
             let returnValueContents = '';
             if (!returnsFunctionArgs &&
                 nestedContent.length === 0 &&
                 dataPaths.length === 1) {
                 returnValueContents = dataPaths[0];
             }
+            else if (returnsFunctionArray &&
+                dataPaths.length === 1 &&
+                !root &&
+                (!nested || nested.length === 0 || hasOnlyArrayPrototypeMethods)) {
+                // Nested method returns an array - return the data path directly
+                // Only if nested content is empty or only contains array prototype methods
+                // (like .reduce() which work on any array - we don't need to mock them)
+                returnValueContents = dataPaths[0];
+            }
             else {
                 if (isArray) {
                     // When GENERIC array (using []) has nested content (like functions that need wrapping),
@@ -523,6 +622,23 @@ export default function constructMockCode(mockName, dependencySchemas) {
                     if (returnValueSection.returnsFunctionArgs && value === 'array') {
                         returnValueSection.returnsFunctionArray = true;
                     }
+                    // Check if this function call has actual return data in the schema
+                    // If the path only has .signature entries (no .functionCallReturnValue), mark as no return data
+                    // Use parts[i] (original part) instead of modified 'part' to include array indices like [1]
+                    const functionCallPath = joinParenthesesAndArrays([
+                        ...parts.slice(0, i),
+                        parts[i], // Use original part which may include [1](args) together
+                    ]);
+                    // Check if there's a .functionCallReturnValue AFTER this function call path
+                    const hasFunctionCallReturnValue = Object.keys(relevantReturnValueSchema).some((k) => {
+                        if (!k.startsWith(functionCallPath))
+                            return false;
+                        const afterPath = k.slice(functionCallPath.length);
+                        return afterPath.startsWith('.functionCallReturnValue');
+                    });
+                    if (!hasFunctionCallReturnValue) {
+                        returnValueSection.hasNoReturnData = true;
+                    }
                 }
                 if (nextIsDifferentiatedArray || hasNestedFunction) {
                     continue;
@@ -648,6 +764,25 @@ export default function constructMockCode(mockName, dependencySchemas) {
                 }
             }
             if (!hasNestedFunction) {
+                // Before breaking, check if this function returns an array
+                // by looking for a functionCallReturnValue: 'array' entry in the schema
+                if (relevantPart && part.endsWith(')')) {
+                    const functionReturnPath = joinParenthesesAndArrays([
+                        ...parts.slice(0, i + 1),
+                        RETURN_VALUE,
+                    ]);
+                    const returnType = relevantReturnValueSchema[functionReturnPath];
+                    if (returnType === 'array') {
+                        // Only set returnsFunctionArray if the array contains plain data,
+                        // NOT if it contains functions (which need wrapping)
+                        const arrayElementPath = `${functionReturnPath}[]`;
+                        const arrayElementType = relevantReturnValueSchema[arrayElementPath];
+                        // If array element is a function, we need to wrap it - don't set returnsFunctionArray
+                        if (arrayElementType !== 'function') {
+                            relevantPart.returnsFunctionArray = true;
+                        }
+                    }
+                }
                 break;
             }
             returnValueSection = relevantPart;
@@ -680,7 +815,23 @@ export default function constructMockCode(mockName, dependencySchemas) {
         return `const ${mockNameParts[0]} = {\n${indent(returnParts.join(',\n'))}\n};`;
     }
     else if (isFunction) {
-        return `const ${mockName}ReturnValue = ${contents};\n\n${isRootAsyncFunction ? 'async ' : ''}function ${mockName}() {\n${indent(`return ${mockName}ReturnValue;`)}\n}`;
+        // For headers() and cookies() from next/headers, add common iterator methods
+        // These are needed when the mock is passed to functions that use .entries(), .keys(), etc.
+        // (e.g., Object.fromEntries(headers.entries()) in buildLegacyHeaders)
+        const needsIteratorMethods = mockName === 'headers' || mockName === 'cookies';
+        let enhancedContents = contents;
+        if (needsIteratorMethods && contents.trim().startsWith('{')) {
+            // Add iterator methods that operate on the scenario data
+            const iteratorMethods = `,
+  entries: () => Object.entries(scenarios().data()?.["${mockName}()"] || {}),
+  keys: () => Object.keys(scenarios().data()?.["${mockName}()"] || {}),
+  values: () => Object.values(scenarios().data()?.["${mockName}()"] || {}),
+  forEach: (fn) => Object.entries(scenarios().data()?.["${mockName}()"] || {}).forEach(([k, v]) => fn(v, k)),
+  has: (key) => Object.prototype.hasOwnProperty.call(scenarios().data()?.["${mockName}()"] || {}, key)`;
+            // Insert before the closing brace (handle trailing whitespace)
+            enhancedContents = contents.replace(/\}\s*$/, iteratorMethods + '\n}');
+        }
+        return `const ${mockName}ReturnValue = ${enhancedContents};\n\n${isRootAsyncFunction ? 'async ' : ''}function ${mockName}() {\n${indent(`return ${mockName}ReturnValue;`)}\n}`;
     }
     else {
         return `const ${mockName} = ${contents}`;