@codeyam/codeyam-cli 0.1.0-staging.dd216e0 → 0.1.0-staging.e090cb3

package/analyzer-template/packages/analyze/src/lib/files/scenarios/mergeInDependentDataStructure.ts

@@ -4,6 +4,7 @@ import {
 } from '~codeyam/ai';
 import { cleanKnownObjectFunctionsFromMapping } from '~codeyam/ai';
 import { DataStructure, Entity, ReadonlyAnalysis } from '~codeyam/types';
+import { transformationTracer } from './TransformationTracer';
 
 export interface DataStructureInfo {
   signatureSchema: { [key: string]: string };
@@ -21,6 +22,78 @@ function cleanFunctionName(functionName: string) {
   return functionName?.split('<')[0];
 }
 
+// Extract the type parameter from a function name, e.g., 'useFetcher<{ data: UserData }>()' -> '{ data: UserData }'
+function getTypeParameter(functionName: string): string | null {
+  if (!functionName) return null;
+  const openBracket = functionName.indexOf('<');
+  if (openBracket === -1) return null;
+  // Find matching closing bracket, accounting for nested brackets
+  let depth = 0;
+  for (let i = openBracket; i < functionName.length; i++) {
+    if (functionName[i] === '<') depth++;
+    else if (functionName[i] === '>') {
+      depth--;
+      if (depth === 0) {
+        return functionName.slice(openBracket + 1, i);
+      }
+    }
+  }
+  return null;
+}
+
+// Primitive types that should not have child paths
+const PRIMITIVE_TYPES = new Set([
+  'number',
+  'string',
+  'boolean',
+  'null',
+  'undefined',
+]);
+
+// Check if a type string represents a primitive type
+// Handles union types like "string | undefined" or "number | null"
+function isPrimitiveType(typeStr: string): boolean {
+  if (PRIMITIVE_TYPES.has(typeStr)) {
+    return true;
+  }
+  // Check union types - if ALL parts of the union are primitives, it's primitive
+  // e.g., "string | undefined" -> ["string", "undefined"] -> both are primitive -> true
+  // e.g., "object | null" -> ["object", "null"] -> object is not primitive -> false
+  if (typeStr.includes('|')) {
+    const parts = typeStr.split('|').map((p) => p.trim());
+    return parts.every((part) => PRIMITIVE_TYPES.has(part));
+  }
+  return false;
+}
+
+// Extract signature index from a path like "signature[0]" or "signature[0].foo"
+// Returns the index number or undefined if not a signature path
+function extractSignatureIndex(path: string): number | undefined {
+  const match = path.match(/^signature\[(\d+)\]/);
+  return match ? parseInt(match[1], 10) : undefined;
+}
+
+// Check if a new schema path would go through a primitive type
+// e.g., if schema has 'entities[].scenarioCount': 'number', then
+// 'entities[].scenarioCount.sha' would go through a primitive and should be rejected
+function wouldGoThroughPrimitive(
+  newPath: string,
+  schema: { [key: string]: string },
+): boolean {
+  const pathParts = splitOutsideParenthesesAndArrays(newPath);
+
+  // Check each prefix of the path (excluding the full path itself)
+  for (let i = 1; i < pathParts.length; i++) {
+    const prefixPath = joinParenthesesAndArrays(pathParts.slice(0, i));
+    const prefixType = schema[prefixPath];
+    if (prefixType && isPrimitiveType(prefixType)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
 // Check if schemaPathPart matches or is a function call variant of pathPart
 // e.g., 'isEntityBeingAnalyzed(entity.sha)' matches 'isEntityBeingAnalyzed'
 function pathPartMatches(pathPart: string, schemaPathPart: string): boolean {
@@ -38,10 +111,14 @@ function bestValueFromOptions(options: Array<string | undefined>) {
   options = options.filter(Boolean) as string[];
 
   const known = options.find((o) => !o.includes('unknown'));
-  if (known) return known;
+  if (known) {
+    return known;
+  }
 
   const notUnknown = options.find((o) => o !== 'unknown');
-  if (notUnknown) return notUnknown;
+  if (notUnknown) {
+    return notUnknown;
+  }
 
   return options[0] ?? 'unknown';
 }
@@ -74,47 +151,6 @@ export default function mergeInDependentDataStructure({
     };
   };
 }) {
-  // writeFile(
-  //   'mergeInDependentDataStructure-debug.json',
-  //   JSON.stringify(
-  //     {
-  //       importedExports: importedExports.map((d) => ({
-  //         filePath: d.filePath,
-  //         name: d.name,
-  //         isMocked: d.isMocked,
-  //       })),
-  //       dependentAnalyses: Object.keys(dependentAnalyses).reduce(
-  //         (pathAcc: Record<string, any>, filePath) => {
-  //           pathAcc[filePath] = Object.keys(dependentAnalyses[filePath]).reduce(
-  //             (nameAcc, name) => {
-  //               nameAcc[name] = {
-  //                 metadata: {
-  //                   mergedDataStructure:
-  //                     dependentAnalyses[filePath][name].metadata
-  //                       .mergedDataStructure,
-  //                 },
-  //               };
-  //               return nameAcc;
-  //             },
-  //             {} as { [name: string]: {
-  //               metadata?: {
-  //                 mergedDataStructure?: ReadonlyAnalysis['metadata']['mergedDataStructure'];
-  //               };
-  //             } },
-  //           );
-  //           return pathAcc;
-  //         },
-  //         {},
-  //       ),
-  //       rootScopeName,
-  //       dataStructure,
-  //       dependencySchemas,
-  //     },
-  //     null,
-  //     2,
-  //   ),
-  // ).catch(() => {});
-
   const mergedDataStructure: Omit<
     DataStructure,
     'equivalentSignatureVariables'
@@ -127,6 +163,44 @@ export default function mergeInDependentDataStructure({
     environmentVariables: [...(dataStructure.environmentVariables || [])],
   };
 
+  // Build a set of functions that have multiple DIFFERENT type parameters.
+  // For these functions, we must NOT normalize paths to avoid merging different schemas.
+  // e.g., if we have both useFetcher<{ data: UserData }>() and useFetcher<{ data: ConfigData }>(),
+  // they must stay separate and not both become 'returnValue'.
+  const functionsWithMultipleTypeParams = new Set<string>();
+  const typeParamsByFunction: Record<string, Set<string>> = {};
+
+  // Helper to scan a schema for type parameters
+  const scanSchemaForTypeParams = (schema: { [key: string]: string }) => {
+    for (const schemaPath of Object.keys(schema ?? {})) {
+      const parts = splitOutsideParenthesesAndArrays(schemaPath);
+      if (parts.length > 0) {
+        const firstPart = parts[0];
+        const typeParam = getTypeParameter(firstPart);
+        if (typeParam) {
+          const baseName = cleanFunctionName(firstPart);
+          typeParamsByFunction[baseName] ||= new Set();
+          typeParamsByFunction[baseName].add(typeParam);
+          if (typeParamsByFunction[baseName].size > 1) {
+            functionsWithMultipleTypeParams.add(baseName);
+          }
+        }
+      }
+    }
+  };
+
+  // Scan the root entity's schema
+  scanSchemaForTypeParams(dataStructure.returnValueSchema);
+
+  // Also scan all dependency schemas for type parameters
+  for (const filePath of Object.keys(dependencySchemas ?? {})) {
+    for (const name of Object.keys(dependencySchemas[filePath] ?? {})) {
+      scanSchemaForTypeParams(
+        dependencySchemas[filePath][name]?.returnValueSchema,
+      );
+    }
+  }
+
   let equivalentSchemaPaths: {
     equivalentRoots: {
       schemaRootPath: string;
@@ -136,10 +210,21 @@ export default function mergeInDependentDataStructure({
     equivalentPostfixes: Record<string, string>;
   }[] = [];
 
+  // Pre-build a lookup map from cleaned function name to dependency for O(1) lookups.
+  // This avoids O(n) linear search in findRelevantDependency which was causing O(n²) performance.
+  const dependencyByCleanedName = new Map<
+    string,
+    (typeof importedExports)[0]
+  >();
+  for (const dep of importedExports) {
+    const cleanedName = cleanFunctionName(dep.name);
+    if (!dependencyByCleanedName.has(cleanedName)) {
+      dependencyByCleanedName.set(cleanedName, dep);
+    }
+  }
+
   const findRelevantDependency = (functionName: any) => {
-    return importedExports.find(
-      (d) => cleanFunctionName(d.name) === cleanFunctionName(functionName),
-    );
+    return dependencyByCleanedName.get(cleanFunctionName(functionName));
   };
 
   const findRelevantDependentDataStructure = (functionName: any) => {
@@ -176,8 +261,17 @@ export default function mergeInDependentDataStructure({
     return mergedDataStructure.dependencySchemas[filePath][name];
   };
 
-  const cleanSchema = (schema: { [key: string]: string }) => {
-    cleanKnownObjectFunctionsFromMapping(schema);
+  const cleanSchema = (
+    schema: { [key: string]: string },
+    context?: Record<string, any>,
+  ) => {
+    transformationTracer.traceSchemaTransform(
+      rootScopeName,
+      'cleanKnownObjectFunctionsFromMapping',
+      schema,
+      cleanKnownObjectFunctionsFromMapping,
+      context,
+    );
   };
 
   const translatePath = (path: string, dependencyName: string) => {
@@ -185,6 +279,15 @@ export default function mergeInDependentDataStructure({
       const pathParts = splitOutsideParenthesesAndArrays(path);
       if (pathParts.length > 1) {
         if (pathParts[1].startsWith('functionCallReturnValue')) {
+          // Check if this function has multiple DIFFERENT type parameters.
+          // If so, DON'T normalize to returnValue - keep the full path to avoid
+          // merging different type-parameterized variants together.
+          // e.g., useFetcher<{ data: UserData }>().functionCallReturnValue.data
+          // should NOT be merged with useFetcher<{ data: ConfigData }>().functionCallReturnValue.data
+          const baseName = cleanFunctionName(pathParts[0]);
+          if (functionsWithMultipleTypeParams.has(baseName)) {
+            return path; // Keep the original path with type parameters
+          }
           // functionCallReturnValue immediately follows - normalize to returnValue
           // e.g., useAuth().functionCallReturnValue.user -> returnValue.user
           return joinParenthesesAndArrays([
@@ -241,10 +344,21 @@ export default function mergeInDependentDataStructure({
       let equivalentSchemaPathsEntry:
         | (typeof equivalentSchemaPaths)[0]
         | undefined;
+
+      // Collect the signature indices from the new roots we want to add
+      const newRootSignatureIndices = new Set<number>();
+      for (const root of equivalentRoots) {
+        const idx = extractSignatureIndex(root.schemaRootPath);
+        if (idx !== undefined) {
+          newRootSignatureIndices.add(idx);
+        }
+      }
+
       for (const pathInfo of allPaths) {
         if (!equivalentSchemaPathsEntry) {
-          equivalentSchemaPathsEntry = equivalentSchemaPaths.find((esp) =>
-            esp.equivalentRoots.some(
+          equivalentSchemaPathsEntry = equivalentSchemaPaths.find((esp) => {
+            // First check: does this entry have a matching root?
+            const hasMatchingRoot = esp.equivalentRoots.some(
               (er) =>
                 er.schemaRootPath === pathInfo.path &&
                 (er.function?.name ===
@@ -252,48 +366,301 @@ export default function mergeInDependentDataStructure({
                   (!er.function &&
                     cleanFunctionName(pathInfo.functionName) ===
                       rootScopeName)),
-            ),
-          );
+            );
+            if (!hasMatchingRoot) return false;
+
+            // Second check: would adding our new roots create a signature index conflict?
+            // An entry should NOT contain roots with different signature indices from the same function.
+            if (newRootSignatureIndices.size > 0) {
+              // Get all signature indices in the existing entry (grouped by function)
+              const existingIndicesByFunction = new Map<string, Set<number>>();
+              for (const er of esp.equivalentRoots) {
+                const funcKey = er.function
+                  ? `${er.function.name}::${er.function.filePath}`
+                  : '__self__';
+                const idx = extractSignatureIndex(er.schemaRootPath);
+                if (idx !== undefined) {
+                  if (!existingIndicesByFunction.has(funcKey)) {
+                    existingIndicesByFunction.set(funcKey, new Set());
+                  }
+                  existingIndicesByFunction.get(funcKey)!.add(idx);
+                }
+              }
+
+              // Check if adding our new roots would create a conflict
+              for (const newRoot of equivalentRoots) {
+                const funcKey = newRoot.function
+                  ? `${newRoot.function.name}::${newRoot.function.filePath}`
+                  : '__self__';
+                const newIdx = extractSignatureIndex(newRoot.schemaRootPath);
+                if (newIdx !== undefined) {
+                  const existingIndices =
+                    existingIndicesByFunction.get(funcKey);
+                  if (existingIndices && existingIndices.size > 0) {
+                    // If this function already has signature indices, check for conflict
+                    if (!existingIndices.has(newIdx)) {
+                      // Conflict: entry has indices like [1] but we want to add [2]
+                      return false;
+                    }
+                  }
+                }
+              }
+            }
+
+            return true;
+          });
         }
       }
 
       if (!equivalentSchemaPathsEntry) {
+        // Before creating a new entry, filter out roots that have conflicting
+        // signature indices from the same function. An entry should never contain
+        // roots with different signature indices from the same function.
+        // This prevents the bug where signature[1], signature[2], signature[4]
+        // all get merged together due to incorrect sourceEquivalencies.
+        let filteredRoots = equivalentRoots;
+        if (newRootSignatureIndices.size > 1) {
+          // There are multiple signature indices - we need to filter to keep only
+          // one consistent set. We'll keep the roots that match the PRIMARY index
+          // (the first signature index we encounter from self, or the lowest index).
+
+          // First, determine the primary index - prefer the self root's index
+          let primaryIndex: number | undefined;
+          for (const root of equivalentRoots) {
+            if (!root.function) {
+              // This is a self root
+              const idx = extractSignatureIndex(root.schemaRootPath);
+              if (idx !== undefined) {
+                primaryIndex = idx;
+                break;
+              }
+            }
+          }
+          // If no self root has a signature index, use the lowest index
+          if (primaryIndex === undefined) {
+            primaryIndex = Math.min(...newRootSignatureIndices);
+          }
+
+          // Filter roots: keep if no signature index OR signature index matches primary
+          filteredRoots = equivalentRoots.filter((root) => {
+            const idx = extractSignatureIndex(root.schemaRootPath);
+            return idx === undefined || idx === primaryIndex;
+          });
+        }
+
         equivalentSchemaPathsEntry = {
-          equivalentRoots,
+          equivalentRoots: filteredRoots,
           equivalentPostfixes: {},
         };
         equivalentSchemaPaths.push(equivalentSchemaPathsEntry);
       } else {
         equivalentSchemaPathsEntry.equivalentRoots.push(...equivalentRoots);
       }
+
+      // Deduplicate roots using a Set for O(n) instead of O(n²)
+      const seenRoots = new Set<string>();
       equivalentSchemaPathsEntry.equivalentRoots =
-        equivalentSchemaPathsEntry.equivalentRoots.filter(
-          (er, index, self) =>
-            index ===
-            self.findIndex(
-              (e) =>
-                e.schemaRootPath === er.schemaRootPath &&
-                e.function?.name === er.function?.name,
-            ),
-        );
+        equivalentSchemaPathsEntry.equivalentRoots.filter((er) => {
+          const key = er.schemaRootPath + '::' + (er.function?.name ?? '');
+          if (seenRoots.has(key)) return false;
+          seenRoots.add(key);
+          return true;
+        });
 
       return equivalentSchemaPathsEntry;
     };
 
-    for (const equivalencies of [
+    // Helper to extract function name from a path that starts with a function call.
+    // e.g., 'ScenarioViewer().signature[0].scenario' -> 'ScenarioViewer'
+    // Returns undefined if the path doesn't start with a function call or the function isn't a dependency.
+    const extractFunctionNameFromPath = (path: string): string | undefined => {
+      const parts = splitOutsideParenthesesAndArrays(path);
+      if (parts.length > 0 && parts[0].endsWith(')')) {
+        // Extract the function name without the () suffix and type params
+        const funcCallPart = parts[0];
+        const funcName = cleanFunctionName(funcCallPart.replace(/\(\)$/, ''));
+        // Check if this function is a dependency
+        if (findRelevantDependency(funcName)) {
+          return funcName;
+        }
+      }
+      return undefined;
+    };
+
+    const allEquivalencies = [
       sourceAndUsageEquivalencies.usageEquivalencies,
       sourceAndUsageEquivalencies.sourceEquivalencies,
-    ].filter(Boolean)) {
-      for (const [schemaPath, usages] of Object.entries(equivalencies)) {
+    ].filter(Boolean);
+
+    for (const equivalencies of allEquivalencies) {
+      const schemaPathEntries = Object.entries(equivalencies);
+      for (const [schemaPath, usages] of schemaPathEntries) {
+        // First, check if the raw schemaPath starts with a function call to a dependency.
+        // If so, use that dependency name for translation (so translatePath can strip the prefix).
+        const extractedFuncName = extractFunctionNameFromPath(schemaPath);
+        const effectiveFunctionName = extractedFuncName || functionName;
+        const translatedPath = translatePath(schemaPath, effectiveFunctionName);
+
         const allPaths: { path: string; functionName?: string }[] = [
-          { path: translatePath(schemaPath, functionName), functionName },
+          { path: translatedPath, functionName: effectiveFunctionName },
           ...usages.map((u) => ({
             path: translatePath(u.schemaPath, u.scopeNodeName),
             functionName: u.scopeNodeName,
           })),
         ].filter((pathInfo) => !pathInfo.path.includes('.map('));
 
+        // Fix 38: Derive base paths from property access paths.
+        // When we have equivalent paths like:
+        //   Parent: signature[0].scenarios[].name
+        //   Child:  signature[0].selectedScenario.name
+        // We want to derive the base paths by finding the common suffix:
+        //   Common suffix: .name
+        //   Parent base: signature[0].scenarios[]
+        //   Child base:  signature[0].selectedScenario
+        // This allows the merge to find nested child schema fields under the base prop.
+
+        // Find child signature paths (paths from child components)
+        const childPaths = allPaths.filter(
+          (p) =>
+            p.functionName &&
+            p.functionName !== rootScopeName &&
+            p.functionName !== effectiveFunctionName,
+        );
+        // Find parent paths (paths from this component)
+        const parentPaths = allPaths.filter(
+          (p) =>
+            !p.functionName ||
+            p.functionName === rootScopeName ||
+            p.functionName === effectiveFunctionName,
+        );
+
+        const derivedBasePaths: { path: string; functionName?: string }[] = [];
+
+        // For each child path, find its equivalent parent path and derive bases
+        for (const childPathInfo of childPaths) {
+          const childParts = splitOutsideParenthesesAndArrays(
+            childPathInfo.path,
+          );
+
+          // Look for a parent path that shares a common suffix with this child path
+          for (const parentPathInfo of parentPaths) {
+            const parentParts = splitOutsideParenthesesAndArrays(
+              parentPathInfo.path,
+            );
+
+            // Find the common suffix (from the end)
+            let commonSuffixLength = 0;
+            const minLen = Math.min(childParts.length, parentParts.length);
+            for (let i = 1; i <= minLen; i++) {
+              if (
+                childParts[childParts.length - i] ===
+                parentParts[parentParts.length - i]
+              ) {
+                commonSuffixLength = i;
+              } else {
+                break;
+              }
+            }
+
+            // If there's a common suffix and both paths have more parts than the suffix
+            if (
+              commonSuffixLength > 0 &&
+              childParts.length > commonSuffixLength &&
+              parentParts.length > commonSuffixLength
+            ) {
+              const childBaseParts = childParts.slice(
+                0,
+                childParts.length - commonSuffixLength,
+              );
+              const parentBaseParts = parentParts.slice(
+                0,
+                parentParts.length - commonSuffixLength,
+              );
+
+              // Only derive if BOTH paths look like signature paths.
+              // This ensures we're handling JSX child-to-parent prop mappings,
+              // not other complex equivalencies like function call returns.
+              const isChildSignaturePath =
+                childBaseParts[0]?.startsWith('signature[') ||
+                (childBaseParts[0]?.endsWith(')') &&
+                  childBaseParts[1]?.startsWith('signature['));
+              const isParentSignaturePath =
+                parentBaseParts[0]?.startsWith('signature[');
+
+              if (isChildSignaturePath && isParentSignaturePath) {
+                const childBase = joinParenthesesAndArrays(childBaseParts);
+                const parentBase = joinParenthesesAndArrays(parentBaseParts);
+
+                // Only derive if:
+                // 1. Parent has array iteration (e.g., scenarios[]) and child does NOT
+                // 2. Bases are different
+                // 3. Child base is NOT just "signature[N]" (too generic - every component has this)
+                //    We only want specific prop paths like "signature[0].selectedScenario"
+                // This targets array-to-object mappings like scenarios[] -> selectedScenario
+                const parentHasArrayIterator = parentBase.includes('[]');
+                const childHasArrayIterator = childBase.includes('[]');
+
+                // Skip if child base is just the generic signature marker (e.g., "signature[0]")
+                const childBaseIsGenericSignature = /^signature\[\d+\]$/.test(
+                  childBase,
+                );
+
+                if (
+                  childBase !== parentBase &&
+                  parentHasArrayIterator &&
+                  !childHasArrayIterator &&
+                  !childBaseIsGenericSignature
+                ) {
+                  // Add child base if not already present
+                  const childBaseExists =
+                    allPaths.some((p) => p.path === childBase) ||
+                    derivedBasePaths.some((p) => p.path === childBase);
+                  if (!childBaseExists) {
+                    derivedBasePaths.push({
+                      path: childBase,
+                      functionName: childPathInfo.functionName,
+                    });
+                  }
+
+                  // Add parent base if not already present
+                  const parentBaseExists =
+                    allPaths.some((p) => p.path === parentBase) ||
+                    derivedBasePaths.some((p) => p.path === parentBase);
+                  if (!parentBaseExists) {
+                    derivedBasePaths.push({
+                      path: parentBase,
+                      functionName: parentPathInfo.functionName,
+                    });
+                  }
+                }
+              }
+            }
+          }
+        }
+
+        allPaths.push(...derivedBasePaths);
+
         const entry = findOrCreateEquivalentSchemaPathsEntry(allPaths);
+
+        // Trace equivalency gathering - helps debug why paths may not be connected
+        if (allPaths.length > 1) {
+          transformationTracer.operation(rootScopeName, {
+            operation: 'gatherEquivalency',
+            stage: 'gathering',
+            path: translatedPath,
+            context: {
+              sourceFunction: functionName,
+              equivalentPaths: allPaths.map((p) => ({
+                path: p.path,
+                function: p.functionName,
+              })),
+              equivalentRoots: entry.equivalentRoots.map((r) => ({
+                path: r.schemaRootPath,
+                function: r.function?.name,
+              })),
+            },
+          });
+        }
         for (const equivalentRoot of entry.equivalentRoots) {
           const dataStructures =
             equivalentRoot.function &&
@@ -308,26 +675,52 @@ export default function mergeInDependentDataStructure({
                 ]
               : [dataStructure];
 
+          // Determine if this is a signature schema path.
+          // The path might be 'signature[0]...' directly, or 'FuncName().signature[0]...' if it has a function prefix.
+          const schemaRootParts = splitOutsideParenthesesAndArrays(
+            equivalentRoot.schemaRootPath,
+          );
+          const isSignaturePath =
+            equivalentRoot.schemaRootPath.startsWith('signature[') ||
+            (schemaRootParts[0]?.endsWith(')') &&
+              schemaRootParts[1]?.startsWith('signature['));
+
           const schemas = dataStructures.map((dataStructure) =>
-            equivalentRoot.schemaRootPath.startsWith('signature[')
+            isSignaturePath
               ? dataStructure?.signatureSchema
               : dataStructure?.returnValueSchema,
           );
 
-          const pathParts = splitOutsideParenthesesAndArrays(
+          let pathParts = splitOutsideParenthesesAndArrays(
             equivalentRoot.schemaRootPath,
           );
 
+          // Fix: When processing a child component's schema, the schemaRootPath has the function
+          // prefix (e.g., 'ScenarioViewer().signature[0].scenario'), but the child's schema paths
+          // don't have that prefix (e.g., 'signature[0].scenario.metadata.screenshotPaths').
+          // Strip the function prefix from pathParts so they can match.
+          if (
+            equivalentRoot.function &&
+            pathParts[0].endsWith(')') &&
+            pathParts[1]?.startsWith('signature[')
+          ) {
+            pathParts = pathParts.slice(1);
+          }
+
           for (const schema of schemas) {
             for (const schemaPath in schema) {
               let schemaPathParts =
                 splitOutsideParenthesesAndArrays(schemaPath);
 
               if (schemaPathParts[0].startsWith(functionName)) {
-                schemaPathParts =
-                  schemaPathParts[1] === 'functionCallReturnValue'
-                    ? ['returnValue', ...schemaPathParts.slice(2)]
-                    : schemaPathParts.slice(1);
+                // Only normalize if the function doesn't have multiple different type parameters
+                const baseName = cleanFunctionName(schemaPathParts[0]);
+                if (!functionsWithMultipleTypeParams.has(baseName)) {
+                  schemaPathParts =
+                    schemaPathParts[1] === 'functionCallReturnValue'
+                      ? ['returnValue', ...schemaPathParts.slice(2)]
+                      : schemaPathParts.slice(1);
+                }
               }
 
               if (schemaPathParts.length < pathParts.length) continue;
@@ -398,13 +791,29 @@ export default function mergeInDependentDataStructure({
                     schemaPathParts.slice(matchedUpToIndex),
                   );
 
-                  entry.equivalentPostfixes[postfix] = entry
-                    .equivalentPostfixes[postfix]
-                    ? bestValueFromOptions([
-                        entry.equivalentPostfixes[postfix],
-                        schema[schemaPath],
-                      ])
-                    : schema[schemaPath];
+                  const previousValue = entry.equivalentPostfixes[postfix];
+                  const newValue = schema[schemaPath];
+                  entry.equivalentPostfixes[postfix] = previousValue
+                    ? bestValueFromOptions([previousValue, newValue])
+                    : newValue;
+
+                  // Trace postfix gathering - shows where type info comes from
+                  if (entry.equivalentPostfixes[postfix] !== previousValue) {
+                    transformationTracer.operation(rootScopeName, {
+                      operation: 'gatherPostfix',
+                      stage: 'gathering',
+                      path: postfix || '(root)',
+                      before: previousValue,
+                      after: entry.equivalentPostfixes[postfix],
+                      context: {
+                        sourceSchemaPath: schemaPath,
+                        sourceFunction:
+                          equivalentRoot.function?.name || rootScopeName,
+                        equivalentRootPath: equivalentRoot.schemaRootPath,
+                        rawValue: newValue,
+                      },
+                    });
+                  }
                 }
               }
             }
@@ -464,14 +873,14 @@ export default function mergeInDependentDataStructure({
           const postfix = joinParenthesesAndArrays(
             schemaPathParts.slice(basePathParts.length),
           );
-          entry.equivalentPostfixes[postfix] = entry.equivalentPostfixes[
-            postfix
-          ]
+          const newValue = entry.equivalentPostfixes[postfix]
             ? bestValueFromOptions([
                 entry.equivalentPostfixes[postfix],
                 dataStructure.returnValueSchema[schemaPath],
               ])
             : dataStructure.returnValueSchema[schemaPath];
+
+          entry.equivalentPostfixes[postfix] = newValue;
         }
       }
     }
@@ -526,6 +935,10 @@ export default function mergeInDependentDataStructure({
       equivalentRootFunction: (typeof equivalentSchemaPaths)[0]['equivalentRoots'][0]['function'],
     ) => {
       let postfix: string | undefined;
+
+      // Get the signature index we're looking for (if any)
+      const lookingForSignatureIndex = extractSignatureIndex(schemaSubPath);
+
       const equivalentEntry = mergedEquivalentSchemaPaths.find((esp) =>
         esp.equivalentRoots.some((er) => {
           if (
@@ -538,6 +951,35 @@ export default function mergeInDependentDataStructure({
           }
 
           if (schemaSubPath === er.schemaRootPath) {
+            // Additional check: if we're looking for a signature path, make sure
+            // the entry doesn't already have DIFFERENT signature indices.
+            // This prevents entries with signature[1], signature[2], signature[4]
+            // from all being merged together.
+            if (lookingForSignatureIndex !== undefined) {
+              const hasConflictingSignatureIndex = esp.equivalentRoots.some(
+                (otherRoot) => {
+                  // Only check roots from the same function
+                  if (
+                    otherRoot.function?.name !== equivalentRootFunction?.name ||
+                    otherRoot.function?.filePath !==
+                      equivalentRootFunction?.filePath
+                  ) {
+                    return false;
+                  }
+                  const otherIndex = extractSignatureIndex(
+                    otherRoot.schemaRootPath,
+                  );
+                  return (
+                    otherIndex !== undefined &&
+                    otherIndex !== lookingForSignatureIndex
+                  );
+                },
+              );
+              if (hasConflictingSignatureIndex) {
+                return false;
+              }
+            }
+
             postfix = er.postfix;
             return true;
           }
@@ -662,16 +1104,54 @@ export default function mergeInDependentDataStructure({
         continue;
       }
 
-      const mergedDataStructure =
+      const childMergedDataStructure =
         dependentAnalyses[filePath][name].metadata?.mergedDataStructure || {};
-      gatherAllEquivalentSchemaPaths(name, mergedDataStructure);
+
+      gatherAllEquivalentSchemaPaths(name, childMergedDataStructure as any);
     }
   }
 
   equivalentSchemaPaths = mergeAllEquivalentSchemaPaths();
 
   for (const esp of equivalentSchemaPaths) {
-    for (const equivalentRoot of esp.equivalentRoots) {
+    // Pre-compute which postfixes have children to avoid O(n²) lookups in the inner loop.
+    // A postfix "has children" if there are other postfixes that extend it.
+    const postfixesWithChildren = new Set<string>();
+    const postfixKeys = Object.keys(esp.equivalentPostfixes);
+
+    // Check for empty postfix having children (any other postfixes exist)
+    if (postfixKeys.length > 1 && '' in esp.equivalentPostfixes) {
+      postfixesWithChildren.add('');
+    }
+
+    // Check for array element postfixes having children using a prefix set.
+    // This avoids O(n²) scans across large postfix lists.
+    // e.g., 'currentEntities[]' has children if a path like 'currentEntities[].sha' exists.
+    const postfixPrefixSet = new Set<string>();
+    for (const postfixPath of postfixKeys) {
+      if (!postfixPath) continue;
+      const parts = splitOutsideParenthesesAndArrays(postfixPath);
+      for (let i = 1; i < parts.length; i++) {
+        postfixPrefixSet.add(joinParenthesesAndArrays(parts.slice(0, i)));
+      }
+    }
+    for (const postfixPath of postfixKeys) {
+      if (postfixPath.endsWith('[]') && postfixPrefixSet.has(postfixPath)) {
+        postfixesWithChildren.add(postfixPath);
+      }
+    }
+
+    // Deduplicate equivalentRoots that would write to the same schema paths.
+    // Roots with the same (function, schemaRootPath, postfix) are redundant.
+    const seenRootKeys = new Set<string>();
+    const uniqueRoots = esp.equivalentRoots.filter((root) => {
+      const key = `${root.function?.filePath ?? ''}::${root.function?.name ?? ''}::${root.schemaRootPath}::${root.postfix ?? ''}`;
+      if (seenRootKeys.has(key)) return false;
+      seenRootKeys.add(key);
+      return true;
+    });
+
+    for (const equivalentRoot of uniqueRoots) {
       let merged:
         | {
             signatureSchema: { [key: string]: string };
@@ -696,9 +1176,21 @@ export default function mergeInDependentDataStructure({
       )) {
         let relevantPostfix = postfixPath;
         if (equivalentRoot.postfix) {
+          // Check if postfixPath starts with equivalentRoot.postfix at a path boundary.
+          // Must ensure exact path part match - "entityCode" should NOT match "entity" prefix.
+          // Valid: "entity.foo" starts with "entity" (boundary at '.')
+          // Valid: "entity[0]" starts with "entity" (boundary at '[')
+          // Invalid: "entityCode" starts with "entity" (no boundary, different property)
           if (!postfixPath.startsWith(equivalentRoot.postfix)) {
             continue;
           }
+          // Additional check: ensure the match is at a path boundary
+          const nextChar = postfixPath[equivalentRoot.postfix.length];
+          if (nextChar !== undefined && nextChar !== '.' && nextChar !== '[') {
+            // The postfixPath continues with more characters that aren't a path separator.
+            // This means "entity" matched "entityCode" which is wrong - they're different properties.
+            continue;
+          }
 
           const postFixPathParts =
             splitOutsideParenthesesAndArrays(postfixPath);
@@ -715,10 +1207,90 @@ export default function mergeInDependentDataStructure({
           relevantPostfix,
         ]);
 
+        // Skip paths that would go through a primitive type
+        // e.g., if schema has 'entities[].scenarioCount': 'number', skip 'entities[].scenarioCount.sha'
+        if (wouldGoThroughPrimitive(newSchemaPath, schema)) {
+          transformationTracer.operation(rootScopeName, {
+            operation: 'skipPrimitivePath',
+            stage: 'merged',
+            path: newSchemaPath,
+            context: {
+              reason: 'would go through primitive type',
+              postfixValue,
+            },
+          });
+          continue;
+        }
+
+        // Skip setting primitive type when there are child postfixes that indicate structure.
+        // This prevents downgrading an object/array element to a primitive type.
+        // Uses pre-computed postfixesWithChildren Set for O(1) lookup instead of O(n) iteration.
+        const hasChildPostfixes =
+          (relevantPostfix === '' || relevantPostfix.endsWith('[]')) &&
+          postfixesWithChildren.has(postfixPath);
+        if (PRIMITIVE_TYPES.has(postfixValue) && hasChildPostfixes) {
+          continue;
+        }
+
+        // Don't overwrite a more specific type with a less specific one
+        // This can happen when nested roots share entries with their parent roots
+        const existingType = schema[newSchemaPath];
+        if (existingType) {
+          // Don't overwrite a primitive type with 'object' or 'array'
+          // e.g., if schema has 'entities[].scenarioCount': 'number', don't overwrite with 'object'
+          if (
+            PRIMITIVE_TYPES.has(existingType) &&
+            (postfixValue === 'object' || postfixValue === 'array')
+          ) {
+            transformationTracer.operation(rootScopeName, {
+              operation: 'skipTypeDowngrade',
+              stage: 'merged',
+              path: newSchemaPath,
+              context: {
+                reason: 'would overwrite primitive with object/array',
+                existingType,
+                newType: postfixValue,
+              },
+            });
+            continue;
+          }
+          // Don't overwrite a complex/union type with a primitive
+          // e.g., if schema has 'scenarios[]': 'Scenario | null', don't overwrite with 'string'
+          if (
+            !PRIMITIVE_TYPES.has(existingType) &&
+            PRIMITIVE_TYPES.has(postfixValue)
+          ) {
+            transformationTracer.operation(rootScopeName, {
+              operation: 'skipTypeDowngrade',
+              stage: 'merged',
+              path: newSchemaPath,
+              context: {
+                reason: 'would overwrite complex type with primitive',
+                existingType,
+                newType: postfixValue,
+              },
+            });
+            continue;
+          }
+        }
+
+        // Log the successful postfix merge
+        transformationTracer.operation(rootScopeName, {
+          operation: 'mergePostfix',
+          stage: 'merged',
+          path: newSchemaPath,
+          before: existingType,
+          after: postfixValue,
+          context: {
+            schemaRootPath: equivalentRoot.schemaRootPath,
+            postfix: relevantPostfix,
+            dependency: equivalentRoot.function?.name,
+          },
+        });
         schema[newSchemaPath] = postfixValue;
       }
 
-      cleanSchema(schema);
+      cleanSchema(schema, { stage: 'afterMergePostfix' });
     }
   }
 
@@ -840,6 +1412,14 @@ export default function mergeInDependentDataStructure({
           `${dependency.name}().functionCallReturnValue`,
         );
       }
+      transformationTracer.operation(rootScopeName, {
+        operation: 'normalizeReturnValuePath',
+        stage: 'merged',
+        path: normalizedPath,
+        before: path,
+        after: normalizedPath,
+        context: { dependency: dependency.name, value },
+      });
       depSchema.returnValueSchema[normalizedPath] = value;
     }
 
@@ -924,7 +1504,214 @@ export default function mergeInDependentDataStructure({
       }
     }
 
-    cleanSchema(depSchema.returnValueSchema);
+    cleanSchema(depSchema.returnValueSchema, {
+      stage: 'afterMockedDependencyMerge',
+      dependency: dependency.name,
+    });
+
+    // Pull signature requirements from downstream functions into the mocked return value.
+    // When a mocked function's return flows into another function's signature (via usageEquivalencies),
+    // we need to include that function's signature requirements in the mock.
+    //
+    // Example: fromE5() returns a currency object that flows to calculateTotalPrice(price, quantity).
+    // calculateTotalPrice's signatureSchema shows signature[0].multiply() is required.
+    // We need to add multiply() to fromE5's mock return value.
+    const usageEquivalencies = srcSchema.usageEquivalencies ?? {};
+    for (const [returnPath, equivalencies] of Object.entries(
+      usageEquivalencies,
+    )) {
+      // Only process return value paths (functionCallReturnValue)
+      if (!returnPath.includes('.functionCallReturnValue')) continue;
+
+      for (const equiv of equivalencies) {
+        // Check if this equivalency points to a signature path
+        const signatureMatch = equiv.schemaPath.match(/\.signature\[(\d+)\]$/);
+        if (!signatureMatch) continue;
+
+        const targetFunctionName = cleanFunctionName(equiv.scopeNodeName);
+        const signatureIndex = signatureMatch[1];
+
+        // Look up the target function's analysis to get its signature requirements
+        // First try dependentAnalyses, then dependencySchemas
+        let targetSignatureSchema: Record<string, string> | undefined;
+
+        // Check dependentAnalyses first (has the full merged analysis)
+        for (const depFilePath in dependentAnalyses) {
+          const analysis = dependentAnalyses[depFilePath]?.[targetFunctionName];
+          if (analysis?.metadata?.mergedDataStructure?.signatureSchema) {
+            targetSignatureSchema =
+              analysis.metadata.mergedDataStructure.signatureSchema;
+            break;
+          }
+        }
+
+        // Fallback to dependencySchemas if not found
+        if (!targetSignatureSchema) {
+          for (const depFilePath in dependencySchemas) {
+            const schema = dependencySchemas[depFilePath]?.[targetFunctionName];
+            if (schema?.signatureSchema) {
+              targetSignatureSchema = schema.signatureSchema;
+              break;
+            }
+          }
+        }
+
+        if (!targetSignatureSchema) continue;
+
+        // Find all paths in the target's signatureSchema that extend from signature[N]
+        // e.g., signature[0].multiply(quantity) -> .multiply(quantity)
+        const signaturePrefix = `signature[${signatureIndex}]`;
+        for (const [sigPath, sigType] of Object.entries(
+          targetSignatureSchema,
+        )) {
+          if (!sigPath.startsWith(signaturePrefix)) continue;
+
+          // Skip the base signature[N] path itself - we only want the method/property extensions
+          if (sigPath === signaturePrefix) continue;
+
+          // Extract the suffix after signature[N] (e.g., ".multiply(quantity)")
+          const suffix = sigPath.slice(signaturePrefix.length);
+
+          // Build the path for the mocked return value
+          // e.g., fromE5(priceE5).functionCallReturnValue.multiply(quantity)
+          const returnValuePath = returnPath + suffix;
+
+          // Add to the mocked dependency's return value schema if not already present
+          if (!(returnValuePath in depSchema.returnValueSchema)) {
+            depSchema.returnValueSchema[returnValuePath] = sigType;
+          }
+        }
+      }
+    }
+
+    cleanSchema(depSchema.returnValueSchema, {
+      stage: 'afterSignatureRequirementsMerge',
+      dependency: dependency.name,
+    });
+  }
+
+  // Process the input dependencySchemas FIRST (before child dependentAnalyses).
+  // This ensures the parent entity's direct usage of dependencies takes precedence.
+  // When both parent and child use the same dependency (e.g., useLoaderData),
+  // the parent's schema paths are preserved, and child's paths are merged in later.
+  //
+  // Some dependencies (like .d.ts type declaration files) may not have:
+  // - Equivalencies with the root scope
+  // - A dependent analysis (they're just type declarations)
+  // - Be marked as mocked
+  // Without this, their schemas would be lost entirely.
+  for (const filePath in dependencySchemas) {
+    for (const name in dependencySchemas[filePath]) {
+      const srcSchema = dependencySchemas[filePath][name];
+      if (!srcSchema) continue;
+
+      // Skip mocked dependencies - they were already processed above with path normalization
+      if (mockedDependencies.has(`${filePath}::${name}`)) {
+        continue;
+      }
+
+      // Check if this dependency was already processed by equivalencies
+      const existingSchema =
+        mergedDataStructure.dependencySchemas[filePath]?.[name];
+
+      // Only add if no existing schema (equivalencies didn't process it)
+      if (!existingSchema) {
+        const depSchema = findOrCreateDependentSchemas({ filePath, name });
+        for (const path in srcSchema.returnValueSchema) {
+          depSchema.returnValueSchema[path] = srcSchema.returnValueSchema[path];
+        }
+        for (const path in srcSchema.signatureSchema) {
+          depSchema.signatureSchema[path] = srcSchema.signatureSchema[path];
+        }
+
+        // Clean known object functions (like String.prototype.replace, Array.prototype.map)
+        // from the copied schema. Without this, method call paths on primitives like
+        // "projectSlug.replace(...)" would cause convertDotNotation to create nested
+        // object structures instead of preserving the primitive type.
+        cleanSchema(depSchema.returnValueSchema, {
+          stage: 'afterDependencySchemaCopy',
+          filePath,
+          dependency: name,
+        });
+      }
+
+      // TYPE REFINEMENT: Check if dependentAnalyses has a more specific type for this dependency.
+      // When a parent passes `entity.filePath` (string | undefined) to a child component
+      // that requires `filePath: string`, we should use the child's more specific type.
+      // This prevents mock data from having undefined values for required props.
+      //
+      // This runs REGARDLESS of whether equivalencies already processed the schema,
+      // because equivalencies copy the parent's type (string | undefined), not the child's
+      // required type (string).
+      const depSchema = findOrCreateDependentSchemas({ filePath, name });
+      const childAnalysis = dependentAnalyses[filePath]?.[name];
+      const childSignatureSchema =
+        childAnalysis?.metadata?.mergedDataStructure?.signatureSchema;
+
+      if (childSignatureSchema) {
+        for (const path in depSchema.signatureSchema) {
+          const parentType = depSchema.signatureSchema[path];
+          const childType = childSignatureSchema[path];
+
+          if (parentType && childType) {
+            // Check if parent has optional type and child has required type
+            const parentIsOptional =
+              parentType.includes('| undefined') ||
+              parentType.includes('| null');
+            const childIsOptional =
+              childType.includes('| undefined') || childType.includes('| null');
+
+            // If child requires a more specific type (not optional), use it
+            if (parentIsOptional && !childIsOptional) {
+              depSchema.signatureSchema[path] = childType;
+            }
+          }
+        }
+      }
+
+      // For functions with multiple different type parameters, also create separate entries
+      // for each type-parameterized variant. This allows gatherDataForMocks to look up
+      // the specific schema for each call signature.
+      // This runs regardless of whether the base entry already existed, since we need
+      // the separate variant entries for proper schema lookup.
+      const baseName = cleanFunctionName(name);
+      if (functionsWithMultipleTypeParams.has(baseName)) {
+        // Find all unique type-parameterized call signatures in the schema
+        const typeParamVariants = new Set<string>();
+        for (const path of Object.keys(srcSchema.returnValueSchema)) {
+          const parts = splitOutsideParenthesesAndArrays(path);
+          if (
+            parts.length > 0 &&
+            parts[0].includes('<') &&
+            parts[0].endsWith(')')
+          ) {
+            typeParamVariants.add(parts[0]);
+          }
+        }
+
+        // Create a separate entry for each type-parameterized variant
+        for (const variant of typeParamVariants) {
+          const variantSchema = findOrCreateDependentSchemas({
+            filePath,
+            name: variant,
+          });
+
+          // Copy only paths that belong to this variant
+          for (const path in srcSchema.returnValueSchema) {
+            if (path.startsWith(variant)) {
+              variantSchema.returnValueSchema[path] =
+                srcSchema.returnValueSchema[path];
+            }
+          }
+          cleanSchema(variantSchema.returnValueSchema, {
+            stage: 'afterTypeVariantCopy',
+            filePath,
+            dependency: name,
+            variant,
+          });
+        }
+      }
+    }
   }
 
   // Ensure ALL dependencies from dependentAnalyses are included in dependencySchemas,
@@ -985,8 +1772,8 @@ export default function mergeInDependentDataStructure({
             // Merge in the nested dependency schemas
             for (const path in nestedDepSchema.returnValueSchema) {
               if (!(path in targetDepSchema.returnValueSchema)) {
-                targetDepSchema.returnValueSchema[path] =
-                  nestedDepSchema.returnValueSchema[path];
+                const value = nestedDepSchema.returnValueSchema[path];
+                targetDepSchema.returnValueSchema[path] = value;
               }
             }
 
@@ -1002,39 +1789,5 @@ export default function mergeInDependentDataStructure({
     }
   }
 
-  // Ensure ALL dependencies from the input dependencySchemas are preserved.
-  // Some dependencies (like .d.ts type declaration files) may not have:
-  // - Equivalencies with the root scope
-  // - A dependent analysis (they're just type declarations)
-  // - Be marked as mocked
-  // Without this, their schemas would be lost entirely.
-  //
-  // IMPORTANT: Only add schemas for dependencies that weren't already processed.
-  // If a dependency has an existing schema (even an empty one), it means the
-  // existing processing (mocked dependencies, equivalencies, dependentAnalyses)
-  // has already handled it and may have intentionally filtered out certain paths.
-  for (const filePath in dependencySchemas) {
-    for (const name in dependencySchemas[filePath]) {
-      const srcSchema = dependencySchemas[filePath][name];
-      if (!srcSchema) continue;
-
-      // Check if this dependency was already processed by any other mechanism
-      const existingSchema =
-        mergedDataStructure.dependencySchemas[filePath]?.[name];
-
-      // Only add if no existing schema at all - this means the dependency
-      // wasn't processed through equivalencies, mocked dependencies, or dependentAnalyses
-      if (!existingSchema) {
-        const depSchema = findOrCreateDependentSchemas({ filePath, name });
-        for (const path in srcSchema.returnValueSchema) {
-          depSchema.returnValueSchema[path] = srcSchema.returnValueSchema[path];
-        }
-        for (const path in srcSchema.signatureSchema) {
-          depSchema.signatureSchema[path] = srcSchema.signatureSchema[path];
-        }
-      }
-    }
-  }
-
   return mergedDataStructure;
 }