@codeyam/codeyam-cli 0.1.0-staging.8e7b1bd → 0.1.0-staging.b8a55ba

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;
+        }
+      }
+    }
+  }
+}

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

@@ -68,6 +68,18 @@ function preprocessSchemaForMocks(
   return result;
 }
 
+/**
+ * Options for gatherDataForMocks
+ */
+export interface GatherDataForMocksOptions {
+  /**
+   * When provided, generates canonical keys in format `EntityName::hookName::index`.
+   * This ensures consistent keys across scenarios regardless of variable names
+   * chosen during analysis.
+   */
+  entityName?: string;
+}
+
 /**
  * Processes a single call (with optional variable name) and returns the mock data entry.
  * Returns null if no valid schema is found.
@@ -78,6 +90,8 @@ function preprocessSchemaForMocks(
  * @param variableNameOccurrence - When a variable name is reused, this is the occurrence index
  *                                  (e.g., first 'data' = 0, second 'data' = 1)
  *                                  Used to disambiguate keys when the same variable is reused.
+ * @param options - Additional options including entityName for canonical key generation
+ * @param hookCallIndex - The global index of this hook call for canonical key generation
  */
 function processCall(
   importedExport: {
@@ -89,20 +103,58 @@ function processCall(
   },
   dependencySchemas: DataStructure['dependencySchemas'],
   callIndex: number,
-  variableNameOccurrence?: number,
+  variableNameOccurrence: number | undefined,
+  options: GatherDataForMocksOptions | undefined,
+  hookCallIndex: number,
 ): { key: string; value: JsonTypeDefinition } | null {
   const callName = importedExport.calls?.[callIndex] ?? importedExport.name;
-  const variableName = importedExport.callVariableNames?.[callIndex];
+  // Determine if we should use variable-qualified schema or base schema.
+  // Use variable-qualified schema when:
+  // 1. variableNameOccurrence is defined (we're processing multiple calls with matching variable names), OR
+  // 2. calls.length equals callVariableNames.length (single call with single variable name)
+  // Use base schema when:
+  // - calls.length !== callVariableNames.length (rest spread or method chain case)
+  // This is important for rest spread destructuring like: const { x, y, ...data } = useLoaderData()
+  // where data.queueState.jobs should come from the base schema, not from a variable-qualified schema.
+  const callsLength = importedExport.calls?.length ?? 0;
+  const varNamesLength = importedExport.callVariableNames?.length ?? 0;
+  const shouldUseVariableQualifiedSchema =
+    variableNameOccurrence !== undefined || callsLength === varNamesLength;
+  const variableName = shouldUseVariableQualifiedSchema
+    ? importedExport.callVariableNames?.[callIndex]
+    : undefined;
 
   // Build the schema lookup key - use variable-qualified key if available
-  const schemaLookupKey = variableName
-    ? `${importedExport.name}::${variableName}`
+  // When the same variable name is reused (variableNameOccurrence > 0), try indexed lookup first
+  // e.g., "useFetcher::fetcher[1]" for the second use of "fetcher"
+  const indexedVariableName =
+    variableName &&
+    variableNameOccurrence !== undefined &&
+    variableNameOccurrence > 0
+      ? `${variableName}[${variableNameOccurrence}]`
+      : variableName;
+
+  const schemaLookupKey = indexedVariableName
+    ? `${importedExport.name}::${indexedVariableName}`
     : importedExport.name;
 
-  const rawSchema =
+  let rawSchema =
     dependencySchemas?.[importedExport.filePath]?.[schemaLookupKey]
       ?.returnValueSchema ?? {};
 
+  // If no schema found with indexed key, try without the index as fallback
+  if (
+    Object.keys(rawSchema).length === 0 &&
+    variableNameOccurrence !== undefined &&
+    variableNameOccurrence > 0 &&
+    variableName
+  ) {
+    const nonIndexedKey = `${importedExport.name}::${variableName}`;
+    rawSchema =
+      dependencySchemas?.[importedExport.filePath]?.[nonIndexedKey]
+        ?.returnValueSchema ?? {};
+  }
+
   // If no schema found with variable-qualified key, fall back to base name
   const fallbackSchema =
     Object.keys(rawSchema).length === 0
@@ -245,13 +297,19 @@ function processCall(
     ? `${baseSchemaKey}::${variableName}`
     : baseSchemaKey;
 
-  // Build output key - for variable-qualified, use "variableName <- functionName" format
-  // This reads naturally as "variableName receives from functionName"
-  // When a variable name is reused (variableNameOccurrence > 0), disambiguate with index
+  // Build output key
+  // When entityName is provided, use canonical key format for consistency across scenarios
+  // Otherwise, use the variable-based format for backward compatibility
   let outputKey: string;
-  if (variableName) {
-    // When the same variable name is used multiple times, append the occurrence index
-    // to create unique keys: "data[0] <- useFetch", "data[1] <- useFetch"
+  if (options?.entityName) {
+    // Canonical key format: EntityName::hookName::index
+    // This ensures consistent keys regardless of variable names chosen during analysis
+    const hookName = cleanFunctionName(importedExport.name);
+    outputKey = `${options.entityName}::${hookName}::${hookCallIndex}`;
+  } else if (variableName) {
+    // Legacy format: "variableName <- functionName"
+    // This reads naturally as "variableName receives from functionName"
+    // When a variable name is reused (variableNameOccurrence > 0), disambiguate with index
     const disambiguator =
       variableNameOccurrence !== undefined && variableNameOccurrence > 0
         ? `[${variableNameOccurrence}]`
@@ -271,6 +329,10 @@ function processCall(
   if (!returnValue) {
     returnValue = schema['returnValue'];
   }
+  // Fallback for function call return values (e.g., useFetcher returns via functionCallReturnValue)
+  if (!returnValue) {
+    returnValue = schema['functionCallReturnValue'];
+  }
 
   if (!returnValue) {
     return null;
@@ -288,11 +350,19 @@ export default function gatherDataForMocks(
     callVariableNames?: string[];
   }[],
   dependencySchemas: DataStructure['dependencySchemas'],
+  options?: GatherDataForMocksOptions,
 ) {
-  return importedExports.reduce(
+  // Track the global index for each hook name across all imports
+  // This enables canonical keys like EntityName::useLoaderData::0, EntityName::useFetcher::0, etc.
+  const hookCallIndices: Record<string, number> = {};
+
+  const result = importedExports.reduce(
     (acc, importedExport) => {
       if (!importedExport.isMocked) return acc;
 
+      // Get the clean hook name for indexing
+      const hookName = cleanFunctionName(importedExport.name);
+
       // Check if we have multiple calls with variable names
       const hasMultipleCalls =
         importedExport.calls &&
@@ -313,21 +383,38 @@ export default function gatherDataForMocks(
           const occurrence = variableNameCounts[varName] ?? 0;
           variableNameCounts[varName] = occurrence + 1;
 
-          const result = processCall(
+          // Get the current hook call index and increment for next call
+          const hookCallIndex = hookCallIndices[hookName] ?? 0;
+          hookCallIndices[hookName] = hookCallIndex + 1;
+
+          const processResult = processCall(
             importedExport,
             dependencySchemas,
             i,
             occurrence,
+            options,
+            hookCallIndex,
           );
-          if (result) {
-            acc[result.key] = result.value;
+          if (processResult) {
+            acc[processResult.key] = processResult.value;
           }
         }
       } else {
         // Original behavior for single calls or calls without variable names
-        const result = processCall(importedExport, dependencySchemas, 0);
-        if (result) {
-          acc[result.key] = result.value;
+        // Get the current hook call index and increment for next call
+        const hookCallIndex = hookCallIndices[hookName] ?? 0;
+        hookCallIndices[hookName] = hookCallIndex + 1;
+
+        const processResult = processCall(
+          importedExport,
+          dependencySchemas,
+          0,
+          undefined,
+          options,
+          hookCallIndex,
+        );
+        if (processResult) {
+          acc[processResult.key] = processResult.value;
         }
       }
 
@@ -335,4 +422,6 @@ export default function gatherDataForMocks(
     },
     {} as { [importAlias: string]: JsonTypeDefinition },
   );
+
+  return result;
 }

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

@@ -38,7 +38,7 @@ export default async function generateChangesScenarioData({
   const fullStructure = analysis.metadata.scenariosDataStructure;
   const structure: Analysis['metadata']['scenariosDataStructure'] = {
     arguments: fullStructure.arguments ?? [],
-    dataForMocks: gatherDataForMocks(analysis, dependentAnalyses),
+    dataForMocks: gatherDataForMocks(analysis, dependentAnalyses, entity.name),
   };
 
   for (const key in fullStructure.dataForMocks) {