@codeyam/codeyam-cli 0.1.0-staging.596f0eb → 0.1.0-staging.76566f9

package/analyzer-template/packages/analyze/src/lib/files/analyze/analyzeEntities/prepareDataStructures.ts

@@ -31,19 +31,6 @@ export default async function prepareEntityDataStructures(
   projectAnalyzer: ProjectAnalyzer,
   options: AnalysisOptions,
 ): Promise<void> {
-  console.log(
-    'CodeYam: prepareEntityDataStructures RUNNING (server-only-detection-v3)',
-  );
-  console.log(
-    `CodeYam: prepareEntityDataStructures processing ${allEntities.size} entities`,
-  );
-
-  // Log all entity names for debugging
-  const entityNames = Array.from(allEntities).map((e) => e.name);
-  console.log(
-    `CodeYam: prepareEntityDataStructures entity names: ${entityNames.join(', ')}`,
-  );
-
   // Process entities in parallel for speed
   await Promise.all(
     Array.from(allEntities).map(async (entity) => {
@@ -117,6 +104,13 @@ export default async function prepareEntityDataStructures(
                 }
               }
 
+              // LOGGING: Track dependencySchemas entity names for debugging :: format issues
+              const allEntityNames: string[] = [];
+              for (const filePath in clonedDependencySchemas) {
+                for (const entityName in clonedDependencySchemas[filePath]) {
+                  allEntityNames.push(`${filePath}:${entityName}`);
+                }
+              }
               entity.metadata.isolatedDataStructure = {
                 signatureSchema: deduplicateFunctionSchemas(
                   isolatedDataStructure.signatureSchema,
@@ -131,6 +125,9 @@ export default async function prepareEntityDataStructures(
                   isolatedDataStructure.environmentVariables,
                 // Use enriched conditional usages with source tracing from analysis
                 conditionalUsages: isolatedDataStructure.conditionalUsages,
+                // Include root entity's equivalencies for merge step
+                usageEquivalencies: isolatedDataStructure.usageEquivalencies,
+                sourceEquivalencies: isolatedDataStructure.sourceEquivalencies,
               };
 
               // Detect wrapper requirements (Context providers, etc.)
@@ -187,10 +184,6 @@ export default async function prepareEntityDataStructures(
         // This runs for ALL entities, even those with cached data structures
         // because server-only detection may have been added after the entity was cached
         const importedExports = entity.metadata?.importedExports ?? [];
-        console.log(
-          `CodeYam: [${entity.name}] Processing ${importedExports.length} importedExports for isMocked determination (cached: ${hasCache})`,
-        );
-
         const mockedDependencies = determineMockedDependencies(entity);
         for (const importedExport of importedExports) {
           // Skip if already has a definitive isMocked value (true or false, not null)
@@ -271,9 +264,14 @@ export default async function prepareEntityDataStructures(
               if (alwaysMockedBrowserGlobals.includes(path)) {
                 info.isMocked = true;
               } else {
+                // Check if this dependency should be mocked
+                // Match both exact entityName and variable-qualified entityNames
+                // e.g., "useFetcher" matches "useFetcher" OR "useFetcher::userFetcher"
                 info.isMocked = mockedDependencies.some(
                   (dep) =>
-                    dep.filePath === path && dep.entityName === info.name,
+                    dep.filePath === path &&
+                    (dep.entityName === info.name ||
+                      dep.entityName.startsWith(info.name + '::')),
                 );
               }
             }
@@ -362,6 +360,108 @@ async function getEntityDataStructureAndFunctionCalls({
           getSourceEquivalencies(dataStructure, importedExport.name) ?? {},
       };
 
+      // Also create variable-qualified entries to preserve distinct return type schemas
+      // when the same function is called multiple times with different type parameters
+      // (e.g., useFetcher<UserData>() vs useFetcher<ReportData>()).
+      //
+      // Each parameterized call is a SEPARATE entry in externalFunctionCalls, so we need
+      // to iterate over ALL matching calls (not just the first one).
+      const matchingCalls = dataStructure.externalFunctionCalls.filter(
+        (fc) =>
+          fc.name === importedExport.name ||
+          fc.name.startsWith(importedExport.name + '<'),
+      );
+
+      for (const efc of matchingCalls) {
+        // Check if this call has perVariableSchemas (multiple calls with same signature)
+        // This is the destructuring case: const { a, b, c } = useLoaderData()
+        // Instead of creating ::variable qualified keys, merge into a single entry
+        // with the call signature as key and named properties in the schema
+        if (efc?.perVariableSchemas) {
+          // Use the call signature as the key (e.g., "useLoaderData<typeof loader>()")
+          const callSignatureKey = efc.callSignature;
+
+          // Merge all variable schemas by prepending the call signature to each path.
+          // perVariableSchemas paths are like "functionCallReturnValue.entities.sha"
+          // We need to prefix them with the call signature to get:
+          // "useLoaderData<typeof loader>().functionCallReturnValue.entities.sha"
+          const mergedReturnValueSchema: Record<string, string> = {};
+
+          // Set the top-level return value as object since it contains named properties
+          mergedReturnValueSchema[
+            `${callSignatureKey}.functionCallReturnValue`
+          ] = 'object';
+
+          for (const [varName, perVarSchema] of Object.entries(
+            efc.perVariableSchemas,
+          )) {
+            for (const [path, type] of Object.entries(perVarSchema)) {
+              // Prepend the call signature to the path
+              // Input: "functionCallReturnValue.entities.sha"
+              // Output: "useLoaderData<typeof loader>().functionCallReturnValue.entities.sha"
+              const rewrittenPath = `${callSignatureKey}.${path}`;
+              mergedReturnValueSchema[rewrittenPath] = type;
+            }
+          }
+
+          acc[importedExport.filePath][callSignatureKey] = {
+            signatureSchema: deduplicateFunctionSchemas({
+              ...signatureSchema,
+            }),
+            returnValueSchema: deduplicateFunctionSchemas(
+              mergedReturnValueSchema,
+            ),
+            usageEquivalencies:
+              getUsageEquivalencies(dataStructure, importedExport.name) ?? {},
+            sourceEquivalencies:
+              getSourceEquivalencies(dataStructure, importedExport.name) ?? {},
+          };
+        } else if (efc?.receivingVariableNames?.length === 1) {
+          // For parameterized calls like useFetcher<UserData>(), each is a separate entry
+          // with a single receivingVariableName. Use the call signature as the key.
+          const varName = efc.receivingVariableNames[0];
+
+          // Use the call signature as the key (e.g., "useFetcher<UserData>()")
+          const callSignatureKey = efc.callSignature;
+
+          // PREFER perVariableSchemas over getReturnValue() when available
+          // perVariableSchemas has the SPECIFIC schema for this parameterized call,
+          // while getReturnValue() may return merged schemas from multiple calls
+          let parameterizedReturnValue: Record<string, string> | null = null;
+
+          if (efc.perVariableSchemas && efc.perVariableSchemas[varName]) {
+            // Use the specific schema from perVariableSchemas
+            parameterizedReturnValue = efc.perVariableSchemas[varName] ?? null;
+          }
+
+          // Fallback to getReturnValue if perCallSignatureSchemas not available
+          if (!parameterizedReturnValue) {
+            parameterizedReturnValue = getReturnValue(dataStructure, {
+              functionName: efc.name, // Use the full parameterized name
+            });
+          }
+
+          if (
+            parameterizedReturnValue &&
+            Object.keys(parameterizedReturnValue).length > 0
+          ) {
+            acc[importedExport.filePath][callSignatureKey] = {
+              signatureSchema: deduplicateFunctionSchemas({
+                ...signatureSchema,
+              }),
+              returnValueSchema: deduplicateFunctionSchemas({
+                ...parameterizedReturnValue,
+              }),
+              usageEquivalencies:
+                getUsageEquivalencies(dataStructure, importedExport.name) ?? {},
+              sourceEquivalencies:
+                getSourceEquivalencies(dataStructure, importedExport.name) ??
+                {},
+            };
+          }
+        }
+      }
+
       return acc;
     },
     {} as {
@@ -394,6 +494,9 @@ async function getEntityDataStructureAndFunctionCalls({
   // Get enriched conditional usages with source tracing
   const conditionalUsages = getConditionalUsages(dataStructure);
 
+  const rawUsageEquivalencies = getUsageEquivalencies(dataStructure);
+  const rawSourceEquivalencies = getSourceEquivalencies(dataStructure);
+
   const isolatedDataStructure = {
     signatureSchema: deduplicateFunctionSchemas(clonedRawSignature),
     returnValueSchema: deduplicateFunctionSchemas(clonedRawReturnValue),
@@ -403,6 +506,11 @@ async function getEntityDataStructureAndFunctionCalls({
     environmentVariables: dataStructure.environmentVariables,
     conditionalUsages:
       Object.keys(conditionalUsages).length > 0 ? conditionalUsages : undefined,
+    // Include root entity's equivalencies so they can be used during merge.
+    // These show how the parent's data flows to/from child components.
+    // E.g., for SurveysList, usageEquivalencies shows surveys[] → SurveyCard().signature[0].survey
+    usageEquivalencies: rawUsageEquivalencies ?? {},
+    sourceEquivalencies: rawSourceEquivalencies ?? {},
   };
 
   const functionCalls: Record<string, string[]> = {};
@@ -415,31 +523,6 @@ async function getEntityDataStructureAndFunctionCalls({
         efc.callSignature.startsWith(entityName),
       );
 
-      // DEBUG: Log external function calls info for useFetcher
-      if (entityName === 'useFetcher' || entityName.includes('Fetcher')) {
-        console.log(
-          'CodeYam DEBUG prepareDataStructures:',
-          JSON.stringify(
-            {
-              entityName,
-              filePath,
-              totalExternalFunctionCalls:
-                dataStructure.externalFunctionCalls.length,
-              matchingCallsCount: matchingCalls.length,
-              matchingCalls: matchingCalls.map((efc) => ({
-                name: efc.name,
-                callSignature: efc.callSignature,
-                allCallSignatures: efc.allCallSignatures,
-                receivingVariableNames: efc.receivingVariableNames,
-                callSignatureToVariable: efc.callSignatureToVariable,
-              })),
-            },
-            null,
-            2,
-          ),
-        );
-      }
-
       // Collect all call signatures from all matching efc entries
       // Each efc may have just one callSignature, or allCallSignatures if merged
       const allSignatures: string[] = [];
@@ -485,6 +568,7 @@ async function getEntityDataStructureAndFunctionCalls({
       ) {
         variableNames.push(...aggregatedReceivingVariableNames);
       }
+
       if (variableNames.length > 0) {
         callVariableNames[entityName] = variableNames;
       }

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

@@ -0,0 +1,158 @@
+import { DataStructure } from '~codeyam/types';
+
+/**
+ * Enriches mocked dependency array types with fields from child component signatures.
+ *
+ * When a mocked dependency (e.g., getSurveysAction) returns an array, and elements
+ * from that array are passed to child components (e.g., SurveyCard), the child's
+ * signatureSchema specifies required fields (e.g., survey.updatedAt). This function
+ * enriches the mocked dependency's returnValueSchema so the LLM knows what fields
+ * to generate for array elements.
+ *
+ * Example:
+ * - getSurveysAction returns { data: array }
+ * - SurveyCard expects signature[0].survey.updatedAt: date
+ * - After enrichment: getSurveysAction().data[]: object, data[].updatedAt: date
+ */
+export default function enrichArrayTypesFromChildSignatures(
+  importedExports: {
+    filePath?: string;
+    name: string;
+    isMocked?: boolean;
+  }[],
+  dependencySchemas: DataStructure['dependencySchemas'],
+): void {
+  // Find all mocked dependencies with array return types
+  const mockedArrayPaths: {
+    filePath: string;
+    entityName: string;
+    arrayPath: string; // e.g., "getSurveysAction().functionCallReturnValue.data"
+  }[] = [];
+
+  for (const importedExport of importedExports) {
+    if (!importedExport.isMocked || !importedExport.filePath) continue;
+
+    const schema =
+      dependencySchemas?.[importedExport.filePath]?.[importedExport.name]
+        ?.returnValueSchema;
+    if (!schema) continue;
+
+    // Find paths that are top-level data arrays (not deeply nested, not direct returns)
+    // We only want to enrich arrays that likely contain objects passed to children
+    // e.g., getSurveysAction().data but NOT:
+    //   - wrapThrows().data.createdBy (deeply nested)
+    //   - getStatusOptions().functionCallReturnValue (direct array return - usually options/primitives)
+    for (const [path, type] of Object.entries(schema)) {
+      if (type !== 'array') continue;
+
+      // Skip paths with computed property patterns like [key], [i], [0], etc.
+      // These represent dynamic access patterns, not simple data arrays
+      // We only match brackets with content (not empty [] which indicates array element type)
+      if (/\[[^\]]+\]/.test(path)) {
+        continue;
+      }
+
+      // Skip direct array returns (e.g., getStatusOptions().functionCallReturnValue)
+      // These are typically specialized arrays like [{label, value}], not entity arrays
+      if (path.endsWith('.functionCallReturnValue')) {
+        continue;
+      }
+
+      // Check if this is a top-level array (at most one property after functionCallReturnValue)
+      // e.g., "foo().functionCallReturnValue.data" is top-level
+      // e.g., "foo().functionCallReturnValue.data.createdBy" is nested (skip)
+      const returnValueMatch = path.match(/\.functionCallReturnValue\.(.+)$/);
+      if (returnValueMatch) {
+        const afterReturnValue = returnValueMatch[1];
+        // If there's more than one property access, it's nested
+        const propertyCount = afterReturnValue.split('.').length;
+        if (propertyCount > 1) {
+          continue; // Skip deeply nested arrays
+        }
+      }
+
+      mockedArrayPaths.push({
+        filePath: importedExport.filePath,
+        entityName: importedExport.name,
+        arrayPath: path,
+      });
+    }
+  }
+
+  if (mockedArrayPaths.length === 0) return;
+
+  // Find all non-mocked child components and extract their signature fields
+  const childSignatureFields: {
+    filePath: string;
+    entityName: string;
+    // Map of prop paths to types, e.g., { "survey.id": "string", "survey.updatedAt": "date" }
+    propFields: Record<string, string>;
+  }[] = [];
+
+  for (const importedExport of importedExports) {
+    // Skip mocked dependencies - we want child components
+    if (importedExport.isMocked || !importedExport.filePath) continue;
+
+    const schema =
+      dependencySchemas?.[importedExport.filePath]?.[importedExport.name]
+        ?.signatureSchema;
+    if (!schema) continue;
+
+    // Extract signature[0].* fields (first prop of child component)
+    const propFields: Record<string, string> = {};
+    for (const [path, type] of Object.entries(schema)) {
+      // Match signature[0].propName.field patterns
+      const match = path.match(/^signature\[0\]\.(\w+)\.(.+)$/);
+      if (match) {
+        const [, propName, fieldPath] = match;
+        // Store as "fieldPath" without the prop name prefix
+        // e.g., signature[0].survey.updatedAt -> updatedAt
+        propFields[fieldPath] = type;
+      }
+    }
+
+    if (Object.keys(propFields).length > 0) {
+      childSignatureFields.push({
+        filePath: importedExport.filePath,
+        entityName: importedExport.name,
+        propFields,
+      });
+    }
+  }
+
+  if (childSignatureFields.length === 0) return;
+
+  // Enrich mocked dependency arrays with child signature fields
+  // Only enrich arrays that don't already have element types defined
+  // A more sophisticated approach would trace the data flow to match specific arrays to specific children
+  for (const { filePath, entityName, arrayPath } of mockedArrayPaths) {
+    const schema = dependencySchemas[filePath][entityName].returnValueSchema;
+
+    // Check if this array already has element type definitions
+    // If so, skip it - it's likely a specialized array like [null] for refs
+    const elementPathPrefix = `${arrayPath}[`;
+    const hasExistingElementType = Object.keys(schema).some((path) =>
+      path.startsWith(elementPathPrefix),
+    );
+
+    if (hasExistingElementType) {
+      // Array already has element type info (e.g., useAutoAnimate()[0]: null)
+      // Don't override it with child signature fields
+      continue;
+    }
+
+    // Add array element type
+    const elementPath = `${arrayPath}[]`;
+    schema[elementPath] = 'object';
+
+    // Add fields from all child signatures to the array element
+    for (const { propFields } of childSignatureFields) {
+      for (const [fieldPath, type] of Object.entries(propFields)) {
+        const fullPath = `${elementPath}.${fieldPath}`;
+        if (!schema[fullPath]) {
+          schema[fullPath] = type;
+        }
+      }
+    }
+  }
+}