@codeyam/codeyam-cli 0.1.0-staging.28f73cf → 0.1.0-staging.2a88920

package/packages/analyze/src/lib/files/scenarios/mergeInDependentDataStructure.js

@@ -1,9 +1,67 @@
-// import { writeFile } from 'node:fs/promises';
 import { splitOutsideParenthesesAndArrays, joinParenthesesAndArrays, } from "../../../../../../packages/ai/index.js";
 import { cleanKnownObjectFunctionsFromMapping } from "../../../../../../packages/ai/index.js";
 function cleanFunctionName(functionName) {
     return functionName?.split('<')[0];
 }
+// Extract the type parameter from a function name, e.g., 'useFetcher<{ data: UserData }>()' -> '{ data: UserData }'
+function getTypeParameter(functionName) {
+    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) {
+    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;
+}
+// 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, schema) {
+    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, schemaPathPart) {
@@ -19,54 +77,16 @@ function pathPartMatches(pathPart, schemaPathPart) {
 function bestValueFromOptions(options) {
     options = options.filter(Boolean);
     const known = options.find((o) => !o.includes('unknown'));
-    if (known)
+    if (known) {
         return known;
+    }
     const notUnknown = options.find((o) => o !== 'unknown');
-    if (notUnknown)
+    if (notUnknown) {
         return notUnknown;
+    }
     return options[0] ?? 'unknown';
 }
 export default function mergeInDependentDataStructure({ importedExports, dependentAnalyses, rootScopeName, dataStructure, dependencySchemas, }) {
-    // 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 = {
         signatureSchema: { ...(dataStructure.signatureSchema ?? {}) },
         returnValueSchema: { ...(dataStructure.returnValueSchema ?? {}) },
@@ -75,9 +95,50 @@ export default function mergeInDependentDataStructure({ importedExports, depende
         dependencySchemas: {},
         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();
+    const typeParamsByFunction = {};
+    // Helper to scan a schema for type parameters
+    const scanSchemaForTypeParams = (schema) => {
+        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] || (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 = [];
+    // 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();
+    for (const dep of importedExports) {
+        const cleanedName = cleanFunctionName(dep.name);
+        if (!dependencyByCleanedName.has(cleanedName)) {
+            dependencyByCleanedName.set(cleanedName, dep);
+        }
+    }
     const findRelevantDependency = (functionName) => {
-        return importedExports.find((d) => cleanFunctionName(d.name) === cleanFunctionName(functionName));
+        return dependencyByCleanedName.get(cleanFunctionName(functionName));
     };
     const findRelevantDependentDataStructure = (functionName) => {
         const dependency = findRelevantDependency(functionName);
@@ -113,6 +174,15 @@ export default function mergeInDependentDataStructure({ importedExports, depende
             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([
@@ -168,24 +238,143 @@ export default function mergeInDependentDataStructure({ importedExports, depende
             else {
                 equivalentSchemaPathsEntry.equivalentRoots.push(...equivalentRoots);
             }
+            // Deduplicate roots using a Set for O(n) instead of O(n²)
+            const seenRoots = new Set();
             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) => {
+            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: 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 = [];
+                // 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);
                 for (const equivalentRoot of entry.equivalentRoots) {
                     const dataStructures = equivalentRoot.function &&
@@ -195,18 +384,37 @@ export default function mergeInDependentDataStructure({ importedExports, depende
                             findRelevantDependentAnalysisDataStructure(equivalentRoot.function.name),
                         ]
                         : [dataStructure];
-                    const schemas = dataStructures.map((dataStructure) => equivalentRoot.schemaRootPath.startsWith('signature[')
+                    // 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) => isSignaturePath
                         ? dataStructure?.signatureSchema
                         : dataStructure?.returnValueSchema);
-                    const pathParts = splitOutsideParenthesesAndArrays(equivalentRoot.schemaRootPath);
+                    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;
@@ -333,6 +541,36 @@ export default function mergeInDependentDataStructure({ importedExports, depende
     };
     const mergeAllEquivalentSchemaPaths = () => {
         const mergedEquivalentSchemaPaths = [];
+        // Pre-pass: Connect entries with array/array-element relationships.
+        // This handles cases like:
+        // - Entry A has root 'surveys' (array)
+        // - Entry B has root 'surveys[]' (array element)
+        // These need to be connected so Entry B's field postfixes flow to Entry A.
+        // We do this before the main merge to ensure the connection happens regardless
+        // of processing order.
+        for (const esp of equivalentSchemaPaths) {
+            for (const root of esp.equivalentRoots) {
+                if (root.schemaRootPath.endsWith('[]')) {
+                    // Find a matching parent entry with the base array path
+                    const baseArrayPath = root.schemaRootPath.slice(0, -2);
+                    const parentEntry = equivalentSchemaPaths.find((other) => other !== esp &&
+                        other.equivalentRoots.some((otherRoot) => otherRoot.schemaRootPath === baseArrayPath &&
+                            otherRoot.function?.name === root.function?.name &&
+                            otherRoot.function?.filePath === root.function?.filePath));
+                    if (parentEntry) {
+                        // Add transformed postfixes from child (array element) to parent (array)
+                        // so they can be applied with [] prefix to parent paths
+                        for (const [postfixPath, postfixValue] of Object.entries(esp.equivalentPostfixes)) {
+                            const transformedPostfix = joinParenthesesAndArrays(['[]', postfixPath].filter(Boolean));
+                            if (!(transformedPostfix in parentEntry.equivalentPostfixes)) {
+                                parentEntry.equivalentPostfixes[transformedPostfix] =
+                                    postfixValue;
+                            }
+                        }
+                    }
+                }
+            }
+        }
         const findEquivalentSchemaPathEntry = (schemaSubPath, equivalentRootFunction) => {
             let postfix;
             const equivalentEntry = mergedEquivalentSchemaPaths.find((esp) => esp.equivalentRoots.some((er) => {
@@ -423,13 +661,48 @@ export default function mergeInDependentDataStructure({ importedExports, depende
             if (mockedDependencies.has(`${filePath}::${name}`)) {
                 continue;
             }
-            const mergedDataStructure = dependentAnalyses[filePath][name].metadata?.mergedDataStructure || {};
-            gatherAllEquivalentSchemaPaths(name, mergedDataStructure);
+            const childMergedDataStructure = dependentAnalyses[filePath][name].metadata?.mergedDataStructure || {};
+            gatherAllEquivalentSchemaPaths(name, childMergedDataStructure);
         }
     }
     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();
+        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();
+        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();
+        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;
             if (equivalentRoot.function) {
                 merged = findOrCreateDependentSchemas(equivalentRoot.function);
@@ -445,9 +718,21 @@ export default function mergeInDependentDataStructure({ importedExports, depende
             for (const [postfixPath, postfixValue] of Object.entries(esp.equivalentPostfixes)) {
                 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);
                     const equivalentRootPostFixParts = splitOutsideParenthesesAndArrays(equivalentRoot.postfix);
                     relevantPostfix = joinParenthesesAndArrays(postFixPathParts.slice(equivalentRootPostFixParts.length));
@@ -456,11 +741,98 @@ export default function mergeInDependentDataStructure({ importedExports, depende
                     equivalentRoot.schemaRootPath,
                     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)) {
+                    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')) {
+                        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)) {
+                        continue;
+                    }
+                }
                 schema[newSchemaPath] = postfixValue;
             }
             cleanSchema(schema);
         }
     }
+    // Propagate equivalency-derived attributes to generic function call variants.
+    // When attributes are traced via equivalencies (e.g., fileComparisons from buildDataMap.signature[2]),
+    // they get written to non-generic paths (returnValue.data.x or funcName().functionCallReturnValue.data.x).
+    // If the ORIGINAL input schema has generic variants (funcName<T>().functionCallReturnValue.data),
+    // we need to copy the attributes to those paths too.
+    for (const filePath in mergedDataStructure.dependencySchemas) {
+        for (const depName in mergedDataStructure.dependencySchemas[filePath]) {
+            const depSchema = mergedDataStructure.dependencySchemas[filePath][depName];
+            const returnValueSchema = depSchema.returnValueSchema;
+            // Look at the ORIGINAL input dependencySchemas for generic variants,
+            // since the merged schema may have lost them during equivalency processing
+            const originalSchema = dependencySchemas?.[filePath]?.[depName];
+            const schemaToSearchForGenericVariants = originalSchema?.returnValueSchema || returnValueSchema;
+            // Find all unique generic variants of this function
+            // e.g., useFetcher<BranchEntityDiffResult>() from useFetcher<BranchEntityDiffResult>().functionCallReturnValue.data
+            const genericVariants = new Set();
+            const genericRegex = new RegExp(`^${depName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}<[^>]+>\\(\\)`);
+            for (const path in schemaToSearchForGenericVariants) {
+                const match = path.match(genericRegex);
+                if (match) {
+                    genericVariants.add(match[0]);
+                }
+            }
+            if (genericVariants.size === 0)
+                continue;
+            // For each returnValue. path or non-generic function call path,
+            // create corresponding paths for each generic variant
+            const pathsToAdd = [];
+            for (const path in returnValueSchema) {
+                const value = returnValueSchema[path];
+                // Handle returnValue. paths
+                if (path.startsWith('returnValue.')) {
+                    const suffix = path.slice('returnValue.'.length);
+                    for (const genericVariant of genericVariants) {
+                        const genericPath = `${genericVariant}.functionCallReturnValue.${suffix}`;
+                        if (!(genericPath in returnValueSchema)) {
+                            pathsToAdd.push([genericPath, value]);
+                        }
+                    }
+                }
+                // Handle non-generic function call paths like depName().functionCallReturnValue.x
+                else if (path.startsWith(`${depName}().functionCallReturnValue.`)) {
+                    const suffix = path.slice(`${depName}().functionCallReturnValue.`.length);
+                    for (const genericVariant of genericVariants) {
+                        const genericPath = `${genericVariant}.functionCallReturnValue.${suffix}`;
+                        if (!(genericPath in returnValueSchema)) {
+                            pathsToAdd.push([genericPath, value]);
+                        }
+                    }
+                }
+            }
+            // Add the new generic variant paths
+            for (const [path, value] of pathsToAdd) {
+                returnValueSchema[path] = value;
+            }
+        }
+    }
     // For mocked dependencies: copy paths from dependencySchemas (usage info) and normalize
     // returnValue. paths that were created by equivalency processing.
     // This ensures all paths use the consistent functionName().functionCallReturnValue. format.
@@ -474,30 +846,32 @@ export default function mergeInDependentDataStructure({ importedExports, depende
             filePath: dependency.filePath,
             name: dependency.name,
         });
-        // First, normalize any returnValue. paths that were written by equivalency processing
-        // to the standard functionName().functionCallReturnValue. format.
-        // Also delete returnValue[] artifact paths that don't represent actual array structure.
+        // First, normalize any returnValue paths that were written by equivalency processing
+        // to the standard functionName().functionCallReturnValue format.
+        // This includes both returnValue. (dot) and returnValue[ (array) paths.
         const pathsToNormalize = [];
-        const pathsToDelete = [];
         for (const path in depSchema.returnValueSchema) {
-            if (path === 'returnValue' || path.startsWith('returnValue.')) {
+            if (path === 'returnValue' ||
+                path.startsWith('returnValue.') ||
+                path.startsWith('returnValue[')) {
                 pathsToNormalize.push([path, depSchema.returnValueSchema[path]]);
             }
-            else if (path.match(/^returnValue\[\d*\]/)) {
-                // Delete returnValue[] and returnValue[n] paths - these are artifacts from
-                // equivalency processing and don't represent the actual structure of mocked dependencies.
-                // The correct structure comes from srcSchema (dependencySchemas).
-                pathsToDelete.push(path);
-            }
-        }
-        for (const path of pathsToDelete) {
-            delete depSchema.returnValueSchema[path];
         }
         for (const [path, value] of pathsToNormalize) {
             delete depSchema.returnValueSchema[path];
-            const normalizedPath = path === 'returnValue'
-                ? `${dependency.name}().functionCallReturnValue`
-                : path.replace(/^returnValue\./, `${dependency.name}().functionCallReturnValue.`);
+            let normalizedPath;
+            if (path === 'returnValue') {
+                normalizedPath = `${dependency.name}().functionCallReturnValue`;
+            }
+            else if (path.startsWith('returnValue.')) {
+                normalizedPath = path.replace(/^returnValue\./, `${dependency.name}().functionCallReturnValue.`);
+            }
+            else {
+                // path.startsWith('returnValue[')
+                // e.g., returnValue[] -> getOptions().functionCallReturnValue[]
+                // e.g., returnValue[].label -> getOptions().functionCallReturnValue[].label
+                normalizedPath = path.replace(/^returnValue/, `${dependency.name}().functionCallReturnValue`);
+            }
             depSchema.returnValueSchema[normalizedPath] = value;
         }
         // Now copy paths from the source schema (dependencySchemas)
@@ -538,8 +912,196 @@ export default function mergeInDependentDataStructure({ importedExports, depende
                     depSchema.returnValueSchema[path] = value;
                 }
             }
+            // Copy object-typed paths for chained API access patterns (like trpc.customer.getCustomersByOrg)
+            // These intermediate paths are needed for constructMockCode to build the nested mock structure.
+            // Example: for trpc.customer.getCustomersByOrg.useQuery().functionCallReturnValue.data,
+            // we need 'trpc', 'trpc.customer', 'trpc.customer.getCustomersByOrg' all typed as 'object'.
+            // Skip paths starting with 'returnValue' - they were already handled above
+            //
+            // EXCEPTION: For function-style dependencies like getSupabase(), skip intermediate object
+            // paths like 'getSupabase().auth' that are just property access after a function call.
+            // These aren't needed because constructMockCode can infer the structure from the actual
+            // function call paths like 'getSupabase().auth.getUser()'. We only need object paths
+            // for object-style dependencies like 'supabase.auth' where the dependency itself is an object.
+            if (value === 'object' && !path.startsWith('returnValue')) {
+                // Check if this is a function-style dependency (path starts with name() or name<T>())
+                const isFunctionStyleDependency = path.startsWith(`${dependency.name}()`) ||
+                    path.match(new RegExp(`^${dependency.name}<[^>]+>\\(\\)`));
+                // For function-style dependencies, skip intermediate object paths
+                // Only keep object paths that are within functionCallReturnValue
+                if (isFunctionStyleDependency &&
+                    !path.includes('.functionCallReturnValue')) {
+                    continue;
+                }
+                if (!(path in depSchema.returnValueSchema)) {
+                    depSchema.returnValueSchema[path] = value;
+                }
+            }
         }
         cleanSchema(depSchema.returnValueSchema);
+        // 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;
+                // 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);
+    }
+    // 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);
+            }
+            // 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();
+                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);
+                }
+            }
+        }
     }
     // Ensure ALL dependencies from dependentAnalyses are included in dependencySchemas,
     // even if they have no equivalencies with the root scope.
@@ -587,8 +1149,8 @@ export default function mergeInDependentDataStructure({ importedExports, depende
                         // 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;
                             }
                         }
                         for (const path in nestedDepSchema.signatureSchema) {
@@ -602,11 +1164,6 @@ export default function mergeInDependentDataStructure({ importedExports, depende
             }
         }
     }
-    // writeFile(
-    //   'mergeInDependentDataStructure-debug-result.json',
-    //   // rootScopeName,
-    //   JSON.stringify(mergedDataStructure, null, 2),
-    // ).catch(() => {});
     return mergedDataStructure;
 }
 //# sourceMappingURL=mergeInDependentDataStructure.js.map