@codeyam/codeyam-cli 0.1.0-staging.15d0f46 → 0.1.0-staging.1669d45

package/analyzer-template/project/constructMockCode.ts

@@ -25,13 +25,102 @@ interface ReturnValuePart {
 }
 
 /**
- * Converts a variable qualifier to a safe identifier for use in function/const names.
- * Handles indexed format like "data[1]" -> "data_1"
+ * Converts a call signature to a valid JavaScript identifier (function name).
+ * The original signature is preserved for data access - this only creates the function name.
+ *
+ * Examples:
+ * - "useAuth()" → "useAuth"
+ * - "db.select(usersQuery)" → "db_select_usersQuery"
+ * - "db.select(postsQuery)" → "db_select_postsQuery"
+ * - "useFetcher<User>()" → "useFetcher_User"
+ * - "useFetcher<{ data: UserData | null }>()" → "useFetcher_data_UserData_null"
+ * - "eq('user_id', value)" → "eq_user_id_value"
+ * - "from('workouts')" → "from_workouts"
  */
-function safeVariableQualifier(qualifier: string): string {
-  // Replace brackets with underscores for valid JS identifier
-  // "data[1]" -> "data_1"
-  return qualifier.replace(/\[(\d+)\]/g, '_$1');
+function callSignatureToFunctionName(signature: string): string {
+  // Extract components from the signature
+  const components: string[] = [];
+
+  // 1. Extract function path (parts separated by dots outside parens/brackets)
+  const pathMatch = signature.match(/^([^<(]+)/);
+  if (pathMatch) {
+    const path = pathMatch[1];
+    // Split on dots but preserve the parts
+    components.push(...path.split('.').filter(Boolean));
+  }
+
+  // 2. Extract generic type parameters (content between < and >)
+  const genericMatch = signature.match(/<([^>]+)>/);
+  if (genericMatch) {
+    const genericContent = genericMatch[1];
+    // Extract meaningful identifiers from generic type
+    // Handle complex types like "{ data: UserData | null }"
+    const typeIdentifiers = genericContent
+      .replace(/[{}:;,]/g, ' ') // Remove structural chars
+      .replace(/\|/g, ' ') // Handle union types
+      .split(/\s+/)
+      .filter(Boolean)
+      .filter((s) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(s)) // Only valid identifiers
+      .filter(
+        (s) =>
+          ![
+            'null',
+            'undefined',
+            'void',
+            'never',
+            'any',
+            'unknown',
+            'data',
+            'typeof',
+          ].includes(s),
+      ); // Skip common non-meaningful keywords
+
+    if (typeIdentifiers.length > 0) {
+      components.push(...typeIdentifiers.slice(0, 2)); // Limit to first 2 for reasonable length
+    }
+  }
+
+  // 3. Extract function arguments (first 2 for disambiguation)
+  const argsMatch = signature.match(/\(([^)]*)\)/);
+  if (argsMatch && argsMatch[1]) {
+    const argsContent = argsMatch[1].trim();
+    if (argsContent) {
+      const args = argsContent.split(',').map((arg) => arg.trim());
+      for (const arg of args.slice(0, 2)) {
+        // For quoted strings, extract the content
+        const stringMatch = arg.match(/^['"`](.+)['"`]$/);
+        if (stringMatch) {
+          // Split on dots for string paths like 'users.id'
+          const parts = stringMatch[1].split('.').filter(Boolean);
+          components.push(...parts);
+        } else if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(arg)) {
+          // Valid identifier - use as-is
+          components.push(arg);
+        } else if (/^\d+$/.test(arg)) {
+          // Number - use as-is
+          components.push(arg);
+        }
+        // Skip complex expressions
+      }
+    }
+  }
+
+  // Build the function name from components
+  const functionName = components
+    .join('_')
+    .replace(/[^a-zA-Z0-9_]/g, '_') // Sanitize special chars
+    .replace(/_+/g, '_') // Collapse multiple underscores
+    .replace(/^_|_$/g, ''); // Trim underscores
+
+  return functionName || 'mock';
+}
+
+/**
+ * Check if a mock name is a call signature (e.g., "useFetcher<User>()", "db.select(query)")
+ */
+function isCallSignature(mockName: string): boolean {
+  // Call signatures contain parentheses (function calls)
+  return mockName.includes('(');
 }
 
 /**
@@ -196,9 +285,12 @@ function funcArgs(functionSignature: string): string[] {
 
 // isValidKey ensures that the key does not contain any characters that would make it invalid in a JavaScript object.
 // For example, it should not contain spaces, special characters, or start with a number.
+// Also rejects keys that are pure function calls like "()" or "(args)" - these aren't property names.
 function isValidKey(key: string) {
   if (!key || key.length === 0) return false;
   const keyWithOutArguments = key.split('(')[0];
+  // Reject empty keys (happens when key is "()" or "(args)") - these are function calls, not property names
+  if (!keyWithOutArguments || keyWithOutArguments.length === 0) return false;
   return !/\s/.test(keyWithOutArguments);
 }
 
@@ -206,20 +298,28 @@ export default function constructMockCode(
   mockName: string,
   dependencySchemas: DeepReadonly<DataStructure['dependencySchemas']>,
   entityType?: EntityType,
-  options?: { keepOriginalFunctionName?: boolean },
+  _canonicalKey?: string, // DEPRECATED: No longer used, kept for API compatibility
+  options?: {
+    keepOriginalFunctionName?: boolean;
+    uniqueFunctionSuffix?: string;
+    skipOriginalSpread?: boolean; // Skip spreading from __cyOriginal when it won't be defined
+  },
 ) {
-  // Check for variable-qualified mock name (e.g., "entityDiffFetcher <- useFetcher")
-  // Format: "variableName <- functionName" which reads naturally as "variableName receives from functionName"
-  // Also handles indexed format: "data[1] <- useFetch" for disambiguating reused variable names
-  const variableQualifierMatch = mockName.match(
-    /^([a-zA-Z_][a-zA-Z0-9_]*(?:\[\d+\])?)\s*<-\s*/,
-  );
-  let variableQualifier = variableQualifierMatch
-    ? variableQualifierMatch[1]
+  // Check if mockName is a call signature (e.g., "useFetcher<User>()", "db.select(query)")
+  const mockNameIsCallSignature = isCallSignature(mockName);
+
+  // For call signatures, use the original signature for data access but generate
+  // a valid JS function name from it
+  const derivedFunctionName = mockNameIsCallSignature
+    ? callSignatureToFunctionName(mockName)
     : null;
-  const baseMockName = variableQualifier
-    ? mockName.slice(variableQualifierMatch[0].length)
-    : mockName;
+
+  // The baseMockName is the function name without type params and args
+  // e.g., "useFetcher<User>()" -> "useFetcher", "db.select(query)" -> "db"
+  const baseMockName = mockName.split(/[<(]/)[0];
+
+  // The data key is the mockName (call signature) for data access
+  let dataKey: string;
 
   const mockNameParts = splitOutsideParenthesesAndArrays(baseMockName);
 
@@ -231,31 +331,10 @@ export default function constructMockCode(
 
   for (const filePath in dependencySchemas) {
     for (const entityName in dependencySchemas[filePath]) {
-      // For variable-qualified mocks, look for the full qualified name first
-      // Format: "variableName <- functionName" (e.g., "entityDiffFetcher <- useFetcher")
-      const targetEntityName = variableQualifier
-        ? `${variableQualifier} <- ${baseMockName}`
-        : mockNameParts[0];
-
-      // Check for direct match
-      let matches =
-        entityName === targetEntityName || entityName === mockNameParts[0];
-
-      // If no direct match and no qualifier was provided, check if the entity
-      // is stored under a variable-qualified key (e.g., "stateBadge <- getStateBadge")
-      // This handles the case where gatherDataForMocks stored the entity with a variable
-      // qualifier but writeScenarioComponents called constructMockCode without one.
-      if (!matches && !variableQualifier) {
-        const qualifiedKeyMatch = entityName.match(
-          new RegExp(`^([a-zA-Z_][a-zA-Z0-9_]*)\\s*<-\\s*${mockNameParts[0]}$`),
-        );
-        if (qualifiedKeyMatch) {
-          matches = true;
-          // Extract the variable qualifier from the entity name so we can use
-          // it for the data lookup key later
-          variableQualifier = qualifiedKeyMatch[1];
-        }
-      }
+      // Match entity by base name (without generics/args)
+      const entityBaseName = entityName.split(/[<(]/)[0];
+      const matches =
+        entityBaseName === baseMockName || entityName === mockNameParts[0];
 
       if (!matches) continue;
 
@@ -299,6 +378,44 @@ export default function constructMockCode(
     }
   }
 
+  // Check if the entity is used as a function (called with ()) vs an object/namespace.
+  // Look for paths in the schema that start with "baseMockName(" or "baseMockName<" indicating function calls.
+  // The "<" handles generic type parameters like useLoaderData<T>().
+  // Also check dataStructurePath === 'returnValue' which indicates a function return value.
+  const entityIsFunction =
+    foundEntityWithSignature ||
+    dataStructurePath === 'returnValue' ||
+    Object.keys(relevantReturnValueSchema ?? {}).some(
+      (key) =>
+        key.startsWith(`${baseMockName}(`) ||
+        key.startsWith(`${baseMockName}<`),
+    );
+
+  // Calculate the data key - use the call signature (mockName) for data access
+  // For simple names without parentheses:
+  // - Append () ONLY if the entity is a function/hook (detected above)
+  // - Don't append () for object/namespace mocks like "supabase"
+  if (mockNameIsCallSignature || mockName.includes('(')) {
+    dataKey = mockName;
+  } else if (entityIsFunction) {
+    // Entity is a function/hook - append () to match call signature format
+    dataKey = `${mockName}()`;
+  } else {
+    // Entity is an object/namespace - use bare name as key
+    dataKey = mockName;
+  }
+
+  // Helper to wrap key in appropriate quotes for computed property access
+  // Use single quotes when key contains double quotes to avoid syntax errors
+  const quotePropertyKey = (key: string): string => {
+    const escaped = key.replace(/\n/g, '\\n');
+    if (escaped.includes('"')) {
+      // Use single quotes, escaping any single quotes in the key
+      return `['${escaped.replace(/'/g, "\\'")}']`;
+    }
+    return `["${escaped}"]`;
+  };
+
   // Check if the return value schema only contains function type markers
   // (e.g., "validateInputs()": "function") without actual return data
   // (no functionCallReturnValue entries)
@@ -327,6 +444,8 @@ export default function constructMockCode(
         key.startsWith('signature['),
       ).length;
       const args = Array.from({ length: argCount }, (_, i) => `arg${i + 1}`);
+      // Always add ...rest to accept extra arguments beyond the signature
+      args.push('...rest');
       const argsString = args.join(', ');
 
       // Generate empty mock function
@@ -351,8 +470,38 @@ export default function constructMockCode(
       key.startsWith('signature['),
     ).length;
     const args = Array.from({ length: argCount }, (_, i) => `arg${i + 1}`);
+    // Always add ...rest to accept extra arguments beyond the signature
+    args.push('...rest');
     const argsString = args.join(', ');
 
+    // Check for Higher-Order Component (HOC) pattern:
+    // - First argument is a function (component) or unknown (couldn't trace type)
+    // - Returns a function
+    // HOCs like memo, forwardRef, createContext should return their first argument
+    //
+    // The return value key can be either:
+    // - 'memo()' (clean format)
+    // - 'memo(({ value, width }: Props) => { ... })' (full component code format)
+    const firstArgIsFunctionOrUnknown =
+      signatureSchema['signature[0]'] === 'function' ||
+      signatureSchema['signature[0]'] === 'unknown';
+    const returnsFunction = relevantReturnValueSchema
+      ? Object.entries(relevantReturnValueSchema).some(([key, value]) => {
+          // Check if key represents a function call that returns a function
+          // Key should start with the mock name, contain '(', end with ')', and have value 'function'
+          const isFunctionCall =
+            key.startsWith(mockName + '(') && key.endsWith(')');
+          return isFunctionCall && value === 'function';
+        })
+      : false;
+
+    if (firstArgIsFunctionOrUnknown && returnsFunction) {
+      // HOC pattern detected - return the first argument
+      return `function ${mockName}(${argsString}) {
+  return arg1;
+}`;
+    }
+
     // Generate empty mock function
     return `function ${mockName}(${argsString}) {
   // Empty mock - original function mocked out
@@ -413,22 +562,21 @@ export default function constructMockCode(
       // so "useLoaderData<typeof loader>()" becomes "useLoaderData()"
       name = cleanOutTypes(name);
 
-      // For variable-qualified mocks at root level, use the "variableName <- functionName" format
-      // This matches the format generated by gatherDataForMocks and is more intuitive for LLMs
-      // e.g., "useFetcher()" becomes "entityDiffFetcher <- useFetcher"
-      if (isRootAccess && variableQualifier) {
-        // Remove trailing () from the function name to match gatherDataForMocks key format
-        const baseName = name.replace(/\(\)$/, '');
-        name = `${variableQualifier} <- ${baseName}`;
+      // For root data access, use the dataKey (original call signature or canonical key)
+      // This preserves the original call signature for LLM clarity
+      if (isRootAccess) {
+        // For call signature format, use the original mockName as the data key
+        // e.g., scenarios().data()?.["useFetcher<User>()"]
+        // e.g., scenarios().data()?.["db.select(usersQuery)"]
+        return `?.${quotePropertyKey(dataKey)}`;
       }
 
       // Only use unquoted array access syntax for pure array indices like [0], [1]
-      // NOT for variable-qualified names like "fetcher[1] <- useFetcher" which need quotes
-      if (name.match(/^\[\d+\]$/) && !name.includes(' <- ')) {
+      if (name.match(/^\[\d+\]$/)) {
         return `?.${name}`;
       }
 
-      return `?.["${name.replace(/\n/g, '\\n')}"]`;
+      return `?.${quotePropertyKey(name)}`;
     };
 
     const constructDataPaths = () => {
@@ -496,7 +644,20 @@ export default function constructMockCode(
         hasNoReturnData,
       } = returnValue;
 
-      const nestedContent: (string | undefined)[] = (nested ?? []).map(
+      // When an array has differentiated indices ([0], [1], etc.), filter out any
+      // non-index items from nested. These non-index items come from generic [] paths
+      // like [].filter or [].sort, which describe element properties, not array elements.
+      // Including them would generate invalid syntax like "sort: ..." inside an array literal.
+      const hasDifferentiatedIndices =
+        isArray &&
+        nested &&
+        nested.some((n) => n.name.match(/^\[\d+\]$/) && n.name !== '[0]');
+      const filteredNested =
+        hasDifferentiatedIndices && nested
+          ? nested.filter((n) => n.name.match(/^\[\d+\]$/))
+          : nested;
+
+      const nestedContent: (string | undefined)[] = (filteredNested ?? []).map(
         (nestedItem) => {
           const nestedContent = constructReturnValueString(
             nestedItem,
@@ -580,53 +741,114 @@ export default function constructMockCode(
       ) {
         levelContentItems.push(...dataPaths.map((path) => `...${path}`));
       }
-      levelContentItems.push(...nestedContent);
+      // Filter out nested content that would be invalid as object properties
+      // (e.g., bare arrow functions like "() => {...}" without a property name)
+      // Only apply this filter when building object content, not array content.
+      // Bare arrow functions ARE valid as array elements (like [0] = {...}, [1] = () => {...})
+      // Check both isArray (item IS an array) and returnsFunctionArray (item returns an array)
+      const inArrayContext = isArray || returnsFunctionArray;
+      const validNestedContent = nestedContent.filter((content) => {
+        if (!content) return false;
+        // Only filter bare arrow functions when NOT in array context
+        // In arrays, bare arrow functions are valid elements
+        if (!inArrayContext && content.match(/^\s*\([^)]*\)\s*=>/)) {
+          return false;
+        }
+        return true;
+      });
+      levelContentItems.push(...validNestedContent);
 
       let levelContents: string = levelContentItems.filter(Boolean).join(',\n');
       if (returnsFunctionArgs) {
-        const argsString = returnsFunctionArgs
-          .map((_, index) => `arg${index + 1}`)
-          .join(', ');
-        let funcContents = '';
-        if (returnsFunctionArray) {
-          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 {
-            funcContents = `return [\n${indent(levelContents)}\n]`;
+        // When returnsFunctionArgs is empty [] OR has a single literal string argument,
+        // the function returns a callable function (e.g., getTranslate() returns t,
+        // where t('key') looks up translations)
+        // Generate a dispatch function that looks up keys based on the argument
+        //
+        // Detect translation-like pattern:
+        // - Data path ends with ["('some.literal')"] - a literal string key
+        // - This means the mock data has keys like "('common.surveys')": "Surveys"
+        // - Exclude ["()"] which is an empty function call (not a translation pattern)
+        const dataPath = dataPaths[0];
+        // Pattern matches ?.["('...')"] at end of path, but NOT ?.["()"] (empty args)
+        const literalKeyPattern = dataPath?.match(/\?\.\["\('.+'\)"\]$/);
+
+        if (
+          !returnsFunctionArray &&
+          dataPaths.length === 1 &&
+          literalKeyPattern // Only dispatch when there's a literal key pattern
+        ) {
+          // Function returns a function - generate dispatch function
+          // Strip the literal key from the path and use dynamic lookup
+          const dataPathBase = literalKeyPattern
+            ? dataPath.replace(/\?\.\["\('.+'\)"\]$/, '')
+            : dataPath;
+          const funcContents = `return ${dataPathBase}?.[\`('\${arg1}')\`]`;
+          levelContents = `(arg1) => {\n${indent(funcContents)}\n}`;
+
+          if (!isArray) {
+            return levelContents;
           }
         } 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) {
-            if (
-              hasNoReturnData ||
-              (hasNestedItems && !hasActualNestedContent)
-            ) {
+          const argsString = returnsFunctionArgs
+            .map((_, index) => `arg${index + 1}`)
+            .join(', ');
+          let funcContents = '';
+          if (returnsFunctionArray) {
+            if (hasNoReturnData) {
               // Function has no return data (only signatures) - return empty array
               funcContents = 'return []';
-            } else {
-              // Has return data - return data path
+            } 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 {
+              funcContents = `return [\n${indent(levelContents)}\n]`;
             }
           } else {
-            funcContents = `return {\n${indent(levelContents)}\n}`;
+            // 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) {
+              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}`;
+            }
           }
-        }
 
-        levelContents = `(${argsString}) => {\n${indent(funcContents)}\n}`;
+          levelContents = `(${argsString}) => {\n${indent(funcContents)}\n}`;
+
+          if (!isArray) {
+            return levelContents;
+          }
+        }
 
-        if (!isArray) {
-          return levelContents;
+        // For generic arrays of functions WITH nested properties (e.g., functionCallReturnValue[] = "function"
+        // with nested .filter, .sort, etc.), the levelContents would be a bare arrow function "() => {...}"
+        // that wraps object content. Using this in a .map(({...})) creates invalid syntax like "({ () => {...} })".
+        // When isGenericArray is true AND there are nested properties, we're accessing data from the elements,
+        // not calling them - so skip the function wrapping.
+        // But if there are NO nested properties, keep the wrapper because callers may want to call the elements.
+        const hasNonStructuralNestedItems =
+          nested &&
+          nested.length > 0 &&
+          nested.some((n) => !n.name.match(/^\[\d*\]$/));
+        if (isGenericArray && hasNonStructuralNestedItems) {
+          // Skip the arrow function wrapper - just use the nested content directly
+          levelContents = levelContentItems.filter(Boolean).join(',\n');
         }
       }
 
@@ -663,24 +885,369 @@ export default function constructMockCode(
           // When GENERIC array (using []) has nested content (like functions that need wrapping),
           // use .map() to transform ALL elements instead of just creating [0]
           // For DIFFERENTIATED arrays (using [0], [1], etc.), keep the static array structure
+          //
+          // IMPORTANT: If the nested content contains differentiated indices like [0], [1],
+          // we MUST use static array pattern, not .map(). The presence of differentiated
+          // indices means the array elements have different types/structures, so .map()
+          // would generate invalid code trying to treat them uniformly.
+          const hasDifferentiatedIndices =
+            nested &&
+            nested.some((n) => n.name.match(/^\[\d+\]$/) && n.name !== '[0]');
           if (
             isGenericArray &&
             nestedContent.length > 0 &&
-            dataPaths.length > 0
+            dataPaths.length > 0 &&
+            !hasDifferentiatedIndices
           ) {
             // Get the array base path (without the [0])
             const arrayBasePath = dataPaths[0].replace(/\?\.\[0\]$/, '');
             // Replace [0] references with [__idx__] in level contents
-            const mappedContents = levelContents.replace(
+            let mappedContents = levelContents.replace(
               /\?\.\[0\]/g,
               '?.[__idx__]',
             );
             // levelContents may already be wrapped in {...} from structural [0] element,
             // so check if we need to add the wrapper or not
             const needsWrapper = !mappedContents.trim().startsWith('{');
+
+            // Helper to check if a position is inside a string literal
+            // Returns the end position of the string if inside one, -1 otherwise
+            // Defined here so it's accessible in both needsWrapper branches
+            const skipStringLiteral = (
+              content: string,
+              pos: number,
+            ): number => {
+              const char = content[pos];
+              if (char !== '"' && char !== "'" && char !== '`') return -1;
+              // Find the matching closing quote
+              let j = pos + 1;
+              while (j < content.length) {
+                if (content[j] === '\\') {
+                  j += 2; // Skip escaped character
+                  continue;
+                }
+                if (content[j] === char) {
+                  return j + 1; // Return position after closing quote
+                }
+                j++;
+              }
+              return content.length; // Unclosed string, skip to end
+            };
+
+            // Filter out bare arrow functions which are invalid as object properties.
+            // Arrow functions can be multi-line, so we need to match the entire function body, not just the first line.
+            // Pattern: starts with "(args) =>", followed by either:
+            //   - A single-line body: "() => expression"
+            //   - A multi-line body: "() => { ... }" (with matching braces)
+            // IMPORTANT: Only filter BARE arrow functions (without property names).
+            // "() => {...}" is invalid, but "get: (arg1) => {...}" is valid.
+            // We use a function to properly handle nested braces.
+            // Defined here so it's accessible in both needsWrapper branches
+            const filterOutArrowFunctions = (content: string): string => {
+              const result: string[] = [];
+              let i = 0;
+              while (i < content.length) {
+                // Skip over string literals entirely
+                const stringEnd = skipStringLiteral(content, i);
+                if (stringEnd !== -1) {
+                  result.push(content.slice(i, stringEnd));
+                  i = stringEnd;
+                  continue;
+                }
+
+                // Check if we're at the start of an arrow function (with optional leading whitespace)
+                const arrowMatch = content
+                  .slice(i)
+                  .match(/^(\s*)\([^)]*\)\s*=>\s*/);
+                if (arrowMatch) {
+                  // Check if this is a bare arrow function or a named property with arrow function value
+                  // Look back to see if there's a "key:" pattern before this position
+                  const before = content.slice(0, i);
+                  const beforeTrimmed = before.trim();
+                  // Valid patterns where arrow function is NOT bare:
+                  // 1. Property value: "key: (arg) => ..." - ends with ':'
+                  // 2. Function argument: ".map((arg) => ..." - ends with '('
+                  // NOTE: We don't include ',' because "{ prop, () => {} }" is invalid
+                  // (can't distinguish function argument from object property context)
+                  const isPropertyValue = beforeTrimmed.endsWith(':');
+                  const isFunctionArg = beforeTrimmed.endsWith('(');
+                  const hasPropertyName = isPropertyValue || isFunctionArg;
+
+                  if (!hasPropertyName) {
+                    // This is a bare arrow function - filter it out
+                    // Found arrow function start, need to find its end
+                    const afterArrow = i + arrowMatch[0].length;
+                    if (content[afterArrow] === '{') {
+                      // Multi-line arrow function - find matching closing brace
+                      // Must respect string literals when counting braces
+                      let braceCount = 1;
+                      let j = afterArrow + 1;
+                      while (j < content.length && braceCount > 0) {
+                        const strEnd = skipStringLiteral(content, j);
+                        if (strEnd !== -1) {
+                          j = strEnd;
+                          continue;
+                        }
+                        if (content[j] === '{') braceCount++;
+                        if (content[j] === '}') braceCount--;
+                        j++;
+                      }
+                      // Skip past the arrow function
+                      i = j;
+                      // Only skip trailing comma, keep newlines
+                      while (i < content.length && content[i] === ' ') {
+                        i++;
+                      }
+                      if (content[i] === ',') {
+                        i++; // Skip the comma after the arrow function
+                      }
+                    } else {
+                      // Single expression arrow function - skip to next comma or newline
+                      let j = afterArrow;
+                      while (
+                        j < content.length &&
+                        content[j] !== ',' &&
+                        content[j] !== '\n'
+                      ) {
+                        j++;
+                      }
+                      i = j;
+                      if (content[i] === ',') i++; // Skip the comma
+                    }
+                    continue;
+                  }
+                }
+                // Not a bare arrow function, keep this character
+                result.push(content[i]);
+                i++;
+              }
+              return result.join('');
+            };
+
+            // Filter out bare object blocks (e.g., "{ ...spread, props }," without a property name)
+            // These are invalid in object literal context - you need "key: { ... }" not just "{ ... }"
+            // Defined here so it's accessible in both needsWrapper branches
+            // The skipFirstBrace parameter allows the else branch to preserve the outer object
+            const filterOutBareObjects = (
+              content: string,
+              skipFirstBrace = false,
+            ): string => {
+              const result: string[] = [];
+              let i = 0;
+              let firstBraceSkipped = false;
+              while (i < content.length) {
+                // Skip over string literals entirely - braces inside strings should not be processed
+                const stringEnd = skipStringLiteral(content, i);
+                if (stringEnd !== -1) {
+                  result.push(content.slice(i, stringEnd));
+                  i = stringEnd;
+                  continue;
+                }
+
+                // Check if we're at a bare object start (newline/comma followed by { without : before it)
+                // Look back to see if there's a colon (property assignment) before this brace
+                const isStartOfLine =
+                  i === 0 ||
+                  content[i - 1] === '\n' ||
+                  content.slice(0, i).trim().endsWith(',');
+                if (content[i] === '{' && isStartOfLine) {
+                  // Check if this is actually a bare object (not "key: {")
+                  const beforeTrimmed = content.slice(0, i).trim();
+                  const isBareObject =
+                    beforeTrimmed.endsWith(',') ||
+                    beforeTrimmed === '' ||
+                    beforeTrimmed.endsWith('(');
+
+                  if (isBareObject) {
+                    // If skipFirstBrace is true and this is the first bare brace at position 0,
+                    // don't filter it - it's the intentional outer object wrapper
+                    if (skipFirstBrace && !firstBraceSkipped && i === 0) {
+                      firstBraceSkipped = true;
+                      result.push(content[i]);
+                      i++;
+                      continue;
+                    }
+
+                    // Find matching closing brace, respecting string literals
+                    let braceCount = 1;
+                    let j = i + 1;
+                    while (j < content.length && braceCount > 0) {
+                      const strEnd = skipStringLiteral(content, j);
+                      if (strEnd !== -1) {
+                        j = strEnd;
+                        continue;
+                      }
+                      if (content[j] === '{') braceCount++;
+                      if (content[j] === '}') braceCount--;
+                      j++;
+                    }
+                    // Skip past the object
+                    i = j;
+                    // Skip trailing comma
+                    while (i < content.length && content[i] === ' ') {
+                      i++;
+                    }
+                    if (content[i] === ',') {
+                      i++;
+                    }
+                    continue;
+                  }
+                }
+                result.push(content[i]);
+                i++;
+              }
+              return result.join('');
+            };
+
+            // Helper to clean up formatting issues after filtering
+            const cleanupContent = (content: string): string => {
+              return (
+                content
+                  .replace(/,\s*,/g, ',') // Double commas
+                  .replace(/,(\s*\n\s*\})/g, '$1') // Trailing comma before closing brace
+                  .replace(/\{\s*\n\s*,/g, '{\n') // Leading comma after opening brace
+                  // Remove incomplete .map calls where callback was filtered out
+                  // Pattern: ".map" followed by newline/whitespace without "(" for args
+                  .replace(/\?\.map(?=\s*[\n\r,}\]])/g, '')
+                  .replace(/\.map(?=\s*[\n\r,}\]])/g, '')
+                  // Clean up orphan })) sequences (from nested filtered map callbacks)
+                  .replace(/\s*\}\)\)\s*\n\s*\}/g, '\n}')
+                  .replace(/^\s*\n/gm, '') // Empty lines
+                  .trim()
+              );
+            };
+
             if (needsWrapper) {
-              returnValueContents = `${arrayBasePath}?.map((__item__, __idx__) => ({\n${indent(mappedContents)}\n}))`;
+              // Apply filters to remove invalid content
+              mappedContents = filterOutArrowFunctions(mappedContents);
+              mappedContents = filterOutBareObjects(mappedContents);
+              mappedContents = cleanupContent(mappedContents);
+
+              // If mappedContents is empty after filtering, don't generate .map() at all
+              // Just use the array path directly with spread or as-is
+              // This prevents orphan )) from empty .map() callbacks
+              const cleanedForEmptyCheck = mappedContents
+                .replace(/\s+/g, '')
+                .replace(/,+/g, '');
+              if (cleanedForEmptyCheck.length === 0) {
+                // Content is empty - just return the array directly
+                returnValueContents = arrayBasePath;
+              } else {
+                // Check if mappedContents is just a bare expression (no property names)
+                // A bare expression like "scenarios().data()?.["key"]?.[__idx__]," cannot be
+                // wrapped in ({ }) because it's not a valid object property.
+                // Pattern: content has no ":" that's not inside brackets/parens/strings
+                const hasBareExpression = (() => {
+                  const trimmed = mappedContents.trim().replace(/,\s*$/, ''); // Remove trailing comma
+                  let depth = 0;
+                  let inString = false;
+                  let stringChar = '';
+                  for (let i = 0; i < trimmed.length; i++) {
+                    const char = trimmed[i];
+                    if (inString) {
+                      if (char === '\\') {
+                        i++; // Skip escaped char
+                        continue;
+                      }
+                      if (char === stringChar) {
+                        inString = false;
+                      }
+                      continue;
+                    }
+                    if (char === '"' || char === "'" || char === '`') {
+                      inString = true;
+                      stringChar = char;
+                      continue;
+                    }
+                    if (char === '(' || char === '[' || char === '{') {
+                      depth++;
+                      continue;
+                    }
+                    if (char === ')' || char === ']' || char === '}') {
+                      depth--;
+                      continue;
+                    }
+                    // Found a colon at depth 0 = has property name
+                    if (char === ':' && depth === 0) {
+                      return false;
+                    }
+                  }
+                  return true;
+                })();
+
+                if (hasBareExpression) {
+                  // Content is just an expression - return it directly without object wrapper
+                  const trimmedContent = mappedContents
+                    .trim()
+                    .replace(/,\s*$/, '');
+                  returnValueContents = `${arrayBasePath}?.map((__item__, __idx__) => (\n${indent(trimmedContent)}\n))`;
+                } else {
+                  returnValueContents = `${arrayBasePath}?.map((__item__, __idx__) => ({\n${indent(mappedContents)}\n}))`;
+                }
+              } // Close the empty content check else block
             } else {
+              // Content already starts with '{'. Check if there are additional properties after the inner object.
+              // If so, we need to merge them INTO the object, not leave them outside.
+              // Pattern: "{ ...spread, props },\nfilter: ...,\nsort: ..."
+              // Should become: "{ ...spread, props, filter: ..., sort: ... }"
+              const trimmed = mappedContents.trim();
+
+              // Find first }, at depth 0 that is NOT inside a string literal
+              // This prevents splitting keys like ?.["useQuery({ id }, { enabled })"]
+              // and also prevents finding }, inside nested arrow functions
+              const findBraceCommaOutsideStrings = (
+                content: string,
+              ): number => {
+                let i = 0;
+                let depth = 0; // Track brace depth to find the outer object's },
+                while (i < content.length - 1) {
+                  // Skip over string literals
+                  const strEnd = skipStringLiteral(content, i);
+                  if (strEnd !== -1) {
+                    i = strEnd;
+                    continue;
+                  }
+                  // Track brace depth
+                  if (content[i] === '{') {
+                    depth++;
+                    i++;
+                    continue;
+                  }
+                  // Check for }, pattern at depth 1 (the outer object level)
+                  // We're looking for the outer object's closing brace, which is at depth 1
+                  // (we started at depth 0, opened { at depth 0 -> 1)
+                  if (content[i] === '}') {
+                    depth--;
+                    if (
+                      depth === 0 &&
+                      i + 1 < content.length &&
+                      content[i + 1] === ','
+                    ) {
+                      return i;
+                    }
+                  }
+                  i++;
+                }
+                return -1;
+              };
+
+              const firstBraceEnd = findBraceCommaOutsideStrings(trimmed);
+              if (firstBraceEnd !== -1) {
+                // Found pattern "{ ... }," followed by more content
+                // Extract the inner object and the trailing properties
+                const innerObject = trimmed.slice(0, firstBraceEnd);
+                const trailingContent = trimmed.slice(firstBraceEnd + 2).trim();
+                if (trailingContent) {
+                  // Merge trailing properties into the inner object
+                  mappedContents = `${innerObject},\n${trailingContent}\n}`;
+                }
+              }
+              // Even when content starts with {, we need to filter out invalid properties inside
+              // (arrow functions and bare objects that were generated from the schema)
+              // Pass skipFirstBrace=true because the content's outer { is the intentional wrapper
+              mappedContents = filterOutArrowFunctions(mappedContents);
+              mappedContents = filterOutBareObjects(mappedContents, true);
+              mappedContents = cleanupContent(mappedContents);
               returnValueContents = `${arrayBasePath}?.map((__item__, __idx__) => (\n${indent(mappedContents)}\n))`;
             }
           } else {
@@ -699,6 +1266,13 @@ export default function constructMockCode(
       if (args && args.length > 0) {
         if (!isValidKey(name)) return;
 
+        // Skip array index patterns like [], [0], [1] when they have args
+        // These represent function calls on array elements, not property keys
+        // e.g., customSizes[].(args) means each array element is callable, not a property named "[]"
+        if (name.match(/^\[\d*\]$/)) {
+          return;
+        }
+
         const mostArgs = args.sort(
           (a: string[], b: string[]) => b.length - a.length,
         )[0];
@@ -758,8 +1332,18 @@ export default function constructMockCode(
             // Use all paths for fallback (existing behavior)
             fallbackContent = `return ${returnValueContents}`;
           } else {
-            // Use all paths as fallback for unknown arguments
-            fallbackContent = `return ${returnValueContents}`;
+            // No explicit fallback paths - return the first literal's value as default
+            // Returning spread of all values is dangerous because if values are primitives (strings),
+            // spreading them creates objects with numeric keys like {0:'a', 1:'b', ...}
+            // which causes "Objects are not valid as React child" errors
+            const firstLiteralValue = literalKeys[0];
+            const firstGroupPaths = argGroups.get(firstLiteralValue);
+            if (firstGroupPaths && firstGroupPaths.length === 1) {
+              fallbackContent = `return ${firstGroupPaths[0]}`;
+            } else {
+              // Multiple paths for first literal - return undefined as safe fallback
+              fallbackContent = `return undefined`;
+            }
           }
 
           const funcContents =
@@ -769,14 +1353,29 @@ export default function constructMockCode(
           content = `${cleanOutTypes(name)}: ${isAsyncFunction ? 'async ' : ''}(${argsString}) => {\n${indent(funcContents)}\n}`;
         } else {
           // No argument variants - use existing behavior
-          const funcContents = `return ${returnValueContents}`;
+          // But if there's nested content, we need to include it in the return object
+          // (similar to how argument variant branches handle this at line 1070-1072)
+          const hasNestedContent = validNestedContent.length > 0;
+          let funcReturnContents: string;
+          if (hasNestedContent && levelContentItems.length > 1) {
+            // Include both spread and nested content in the return
+            funcReturnContents = `{\n${indent(levelContents)}\n}`;
+          } else {
+            funcReturnContents = returnValueContents;
+          }
+          const funcContents = `return ${funcReturnContents}`;
           content = `${cleanOutTypes(name)}: ${isAsyncFunction ? 'async ' : ''}(${argsString}) => {\n${indent(funcContents)}\n}`;
         }
       } else {
         if (!isValidKey(name)) {
           return;
         } else if (name.match(/\[\d*\]/)) {
+          // Numeric array index like [0], [1] - can be used as computed property
           content = returnValueContents;
+        } else if (name.match(/^\[[a-zA-Z_]\w*\]$/)) {
+          // Variable-based index like [currentItemIndex] - must be quoted string key
+          // Otherwise JavaScript would try to evaluate the variable name
+          content = `"${safeString(name)}": ${returnValueContents}`;
         } else {
           content = `${safeString(name)}: ${returnValueContents}`;
         }
@@ -853,8 +1452,8 @@ export default function constructMockCode(
       }
     }
 
-    // For variable-qualified mocks like "revalidator <- useRevalidator",
-    // compare against baseMockName ("useRevalidator"), not the full mockName
+    // Compare against baseMockName (without generics/args), not the full mockName
+    // e.g., for "useFetcher<User>()", baseMockName is "useFetcher"
     if (parts[0].split('(')[0] !== baseMockName) continue;
 
     // Include paths with functionCallReturnValue OR function-typed paths that need mocking
@@ -970,6 +1569,17 @@ export default function constructMockCode(
       const nextIsArray = !!nextPart?.match(/^\[\d*\]/);
       const isDifferentiatedArray = !!part?.match(/^\[\d+\]/);
       const nextIsDifferentiatedArray = !!nextPart?.match(/^\[\d+\]/);
+
+      // Variable index patterns like [currentItemIndex] or [targetIndex] indicate array access
+      // but don't represent actual data structure - they're markers from variable-based index tracking.
+      // Skip them AND all remaining parts to avoid creating spurious nested structure that breaks array iteration.
+      // The remaining parts (e.g., .missing_attributes) describe properties of array elements, which are
+      // already handled by the generic [] accessor path.
+      const isVariableIndex = !!part?.match(/^\[[a-zA-Z_]\w*\]$/);
+      if (isVariableIndex) {
+        // Break out of the loop entirely - don't process any remaining parts
+        break;
+      }
       // Find the correct value for the current part being processed
       let partValue = value; // default to the final value
       if (isFunctionCallReturnValue(part) && nextIsArray) {
@@ -1077,7 +1687,52 @@ export default function constructMockCode(
                 }
               }
             } else {
-              returnValueSection.returnsFunctionArgs = [];
+              // Before setting returnsFunctionArgs on the parent (for generic [] = function),
+              // check if there are specific array indices (like [0], [1]) that are NOT functions.
+              // If so, don't set returnsFunctionArgs because those specific indices take precedence.
+              // This prevents adding ["()"] to paths like [0] when [0] is 'unknown' but [] is 'function'.
+              //
+              // Use parts.slice(0, i + 1) to get the current path INCLUDING functionCallReturnValue.
+              // For example, if parts = ['useAtom()','functionCallReturnValue','[]']
+              // and i = 1, we want to check 'useAtom().functionCallReturnValue[0]' etc.
+              const arrayContainerPath = joinParenthesesAndArrays(
+                parts.slice(0, i + 1),
+              );
+
+              const hasNonFunctionSpecificIndices = Object.entries(
+                relevantReturnValueSchema,
+              ).some(([k, v]) => {
+                // Look for paths like "arrayContainerPath[0]", "arrayContainerPath[1]" etc.
+                const indexMatch = k.match(
+                  new RegExp(
+                    `^${arrayContainerPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\[(\\d+)\\]$`,
+                  ),
+                );
+                // If found and it's NOT a function type, we have a conflict
+                return (
+                  indexMatch &&
+                  !['function', 'async-function'].includes(v as string)
+                );
+              });
+
+              // Also check if [] has nested object properties (like [].filter, [].name)
+              // If so, [] items are objects with properties, not pure functions to be called
+              // This handles cases where the schema shows [].filter = object but doesn't
+              // have explicit [0] entries
+              const genericArrayPath = `${arrayContainerPath}[]`;
+              const hasNestedProperties = Object.keys(
+                relevantReturnValueSchema,
+              ).some((k) => {
+                // Check for paths like "arrayContainerPath[].propertyName" (not [].())
+                return (
+                  k.startsWith(genericArrayPath + '.') &&
+                  !k.startsWith(genericArrayPath + '.(')
+                );
+              });
+
+              if (!hasNonFunctionSpecificIndices && !hasNestedProperties) {
+                returnValueSection.returnsFunctionArgs = [];
+              }
             }
           }
         }
@@ -1102,7 +1757,8 @@ export default function constructMockCode(
             }
             // If the next part is an object with nested content, continue processing
             // This handles paths like functionCallReturnValue.selectedOptions.elementOptions[]
-            if (nextValue === 'object' || nextValue === 'array') {
+            // Also handles union types like 'array | undefined' or 'object | undefined'
+            if (nextValue?.includes('object') || nextValue?.includes('array')) {
               continue;
             }
           }
@@ -1256,7 +1912,14 @@ export default function constructMockCode(
         relevantPart.isGenericArray = true;
       }
 
-      if (!hasNestedFunction) {
+      // Check if there are remaining parts after functionCallReturnValue that need processing
+      // (e.g., data properties like useQuery().functionCallReturnValue.data)
+      const hasRemainingPartsAfterReturnValue =
+        nextPart &&
+        (isFunctionCallReturnValue(nextPart) ||
+          (isFunctionCallReturnValue(parts[i]) && i < parts.length - 1));
+
+      if (!hasNestedFunction && !hasRemainingPartsAfterReturnValue) {
         // Before breaking, check if this function returns an array
         // by looking for a functionCallReturnValue: 'array' entry in the schema
         if (relevantPart && part.endsWith(')')) {
@@ -1288,6 +1951,7 @@ export default function constructMockCode(
 
   if (mockNameParts.length > 1) {
     const originalLib = `${mockNameParts[0]}__cyOriginal`;
+    const skipOriginalSpread = options?.skipOriginalSpread;
 
     const subPart = (
       parts: string[],
@@ -1299,7 +1963,9 @@ export default function constructMockCode(
 
       const partContents = isLast
         ? contents
-        : `...${originalLib}.${part},\n${subPart(parts, originalLib)}`;
+        : skipOriginalSpread
+          ? subPart(parts, originalLib)
+          : `...${originalLib}.${part},\n${subPart(parts, originalLib)}`;
 
       let code = `${part}: {\n${indent(partContents)}\n}`;
 
@@ -1313,27 +1979,31 @@ export default function constructMockCode(
       return code;
     };
 
-    const returnParts = [
-      `...${mockNameParts[0]}__cyOriginal`,
-      subPart(mockNameParts.slice(1), originalLib),
-    ].filter(Boolean);
+    const returnParts = skipOriginalSpread
+      ? [subPart(mockNameParts.slice(1), originalLib)]
+      : [
+          `...${mockNameParts[0]}__cyOriginal`,
+          subPart(mockNameParts.slice(1), originalLib),
+        ];
 
-    return `const ${mockNameParts[0]} = {\n${indent(returnParts.join(',\n'))}\n};`;
+    return `const ${mockNameParts[0]} = {\n${indent(returnParts.filter(Boolean).join(',\n'))}\n};`;
   } else if (isFunction) {
     // 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';
+      baseMockName === 'headers' || baseMockName === 'cookies';
     let enhancedContents = contents;
     if (needsIteratorMethods && contents.trim().startsWith('{')) {
       // Add iterator methods that operate on the scenario data
+      // Use the dataKey (original call signature or canonical key)
+      const quotedDataKey = quotePropertyKey(dataKey);
       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)`;
+  entries: () => Object.entries(scenarios().data()?.${quotedDataKey} || {}),
+  keys: () => Object.keys(scenarios().data()?.${quotedDataKey} || {}),
+  values: () => Object.values(scenarios().data()?.${quotedDataKey} || {}),
+  forEach: (fn) => Object.entries(scenarios().data()?.${quotedDataKey} || {}).forEach(([k, v]) => fn(v, k)),
+  has: (key) => Object.prototype.hasOwnProperty.call(scenarios().data()?.${quotedDataKey} || {}, key)`;
       // Insert before the closing brace (handle trailing whitespace)
       enhancedContents = contents.replace(/\}\s*$/, iteratorMethods + '\n}');
     }
@@ -1344,40 +2014,106 @@ export default function constructMockCode(
     // `new ClassName("arg")` wouldn't create the expected instance.
     // For Error subclasses (detected by name ending in "Error"), extend Error for proper error handling.
     if (entityType === 'class') {
-      const isErrorSubclass = mockName.endsWith('Error');
-      const baseClass = isErrorSubclass ? 'Error' : 'Object';
+      const isErrorSubclass = baseMockName.endsWith('Error');
       const superCall = isErrorSubclass ? 'super(message);' : '';
       const nameAssignment = isErrorSubclass
-        ? `this.name = '${mockName}';`
+        ? `this.name = '${baseMockName}';`
         : '';
+      // Use the safe function name for the class definition
+      const className = mockNameIsCallSignature
+        ? derivedFunctionName
+        : baseMockName;
 
-      return `class ${mockName}${isErrorSubclass ? ' extends Error' : ''} {
+      return `class ${className}${isErrorSubclass ? ' extends Error' : ''} {
   constructor(message) {
     ${superCall}
     ${nameAssignment}
-    Object.assign(this, scenarios().data()?.["${mockName}()"] || {});
+    Object.assign(this, scenarios().data()?.${quotePropertyKey(dataKey)} || {});
   }
 }`;
     }
 
-    // For variable-qualified mocks, use underscore separator in the function name
-    // e.g., "entityDiffFetcher <- useFetcher" becomes "useFetcher_entityDiffFetcher"
-    // For indexed qualifiers like "data[1]", convert to safe identifier: "useFetcher_data_1"
-    // EXCEPTION: When keepOriginalFunctionName is true (for single-call cases), use the base name
-    const safeFunctionName =
-      variableQualifier && !options?.keepOriginalFunctionName
-        ? `${baseMockName}_${safeVariableQualifier(variableQualifier)}`
-        : baseMockName;
+    // Generate safe function name:
+    // 1. For call signatures: use derivedFunctionName
+    //    e.g., "useFetcher<User>()" becomes "useFetcher_User"
+    //    e.g., "db.select(usersQuery)" becomes "db_select_usersQuery"
+    // 2. With uniqueFunctionSuffix option: append suffix for unique naming
+    //    e.g., baseMockName = "useFetcher", suffix = "entityDiffFetcher" -> "useFetcher_entityDiffFetcher"
+    // 3. EXCEPTION: When keepOriginalFunctionName is true (for single-call cases), use the base name
+    let safeFunctionName: string;
+    if (options?.keepOriginalFunctionName) {
+      safeFunctionName = baseMockName;
+    } else if (options?.uniqueFunctionSuffix) {
+      safeFunctionName = `${baseMockName}_${options.uniqueFunctionSuffix}`;
+    } else if (mockNameIsCallSignature && derivedFunctionName) {
+      safeFunctionName = derivedFunctionName;
+    } else {
+      safeFunctionName = baseMockName;
+    }
+
+    // Check if this function returns a function (detected by double-call pattern: mockName(args)())
+    // This happens when the schema has keys like "wrapThrows(() => JSON.parse(savedFilters))()"
+    // where the function call is immediately followed by another call.
+    // Example usage: const result = wrapThrows(() => JSON.parse(x))(); // double call
+    const isHigherOrderFunction = Object.keys(
+      relevantReturnValueSchema ?? {},
+    ).some((key) => {
+      if (!key.startsWith(baseMockName)) return false;
+
+      // Find the first ( after baseMockName (the start of the function call)
+      const firstOpenParen = key.indexOf('(', baseMockName.length);
+      if (firstOpenParen === -1) return false;
+
+      // Skip if the ( is not immediately after the mock name
+      // (there might be type params like func<T>() - handle by checking for < or ()
+      const between = key.slice(baseMockName.length, firstOpenParen);
+      if (between.length > 0 && !between.startsWith('<')) return false;
+
+      // Find the matching ) for the first ( using depth counting
+      let depth = 1;
+      let i = firstOpenParen + 1;
+      while (i < key.length && depth > 0) {
+        if (key[i] === '(') depth++;
+        if (key[i] === ')') depth--;
+        i++;
+      }
+
+      if (depth !== 0) return false; // Unbalanced parentheses
+
+      // Now i points just after the matching )
+      // Check if there's another ( immediately (indicating double call)
+      const remaining = key.slice(i);
+      if (remaining.startsWith('(')) return true;
+
+      return false;
+    });
 
-    return `const ${safeFunctionName}ReturnValue = ${enhancedContents};\n\n${isRootAsyncFunction ? 'async ' : ''}function ${safeFunctionName}() {\n${indent(`return ${safeFunctionName}ReturnValue;`)}\n}`;
+    // Use ...args to accept any number of arguments - prevents TypeScript errors
+    // like "Expected 0 arguments, but got X" when caller passes arguments
+    // For higher-order functions, wrap the return in an arrow function
+    // so that mockFunc(arg)() works correctly (outer call returns a function, inner call gets the data)
+    const returnValue = isHigherOrderFunction
+      ? `() => (${enhancedContents})`
+      : enhancedContents;
+
+    // Inline the return value directly in the function to avoid module-level const
+    // that would be evaluated before scenario context is ready
+    return `${isRootAsyncFunction ? 'async ' : ''}function ${safeFunctionName}(...args) {\n${indent(`return ${returnValue};`)}\n}`;
   } else {
-    // For variable-qualified mocks, use underscore separator in the const name
-    // For indexed qualifiers like "data[1]", convert to safe identifier: "useFetcher_data_1"
-    // EXCEPTION: When keepOriginalFunctionName is true (for single-call cases), use the base name
-    const safeName =
-      variableQualifier && !options?.keepOriginalFunctionName
-        ? `${baseMockName}_${safeVariableQualifier(variableQualifier)}`
-        : baseMockName;
+    // Generate safe const name:
+    // 1. For call signatures: use derivedFunctionName
+    // 2. With uniqueFunctionSuffix option: append suffix for unique naming
+    // 3. EXCEPTION: When keepOriginalFunctionName is true (for single-call cases), use the base name
+    let safeName: string;
+    if (options?.keepOriginalFunctionName) {
+      safeName = baseMockName;
+    } else if (options?.uniqueFunctionSuffix) {
+      safeName = `${baseMockName}_${options.uniqueFunctionSuffix}`;
+    } else if (mockNameIsCallSignature && derivedFunctionName) {
+      safeName = derivedFunctionName;
+    } else {
+      safeName = baseMockName;
+    }
 
     // Get any jsx-component properties that need to be preserved from the original
     const jsxProperties = getJsxComponentProperties(