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

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

@@ -3,6 +3,7 @@ import {
   convertDotNotation,
   fillInDirectSchemaGapsAndUnknowns,
   joinParenthesesAndArrays,
+  mergeJsonTypeDefinitions,
   splitOutsideParenthesesAndArrays,
 } from '~codeyam/ai';
 import { DataStructure, JsonTypeDefinition } from '~codeyam/types';
@@ -15,6 +16,65 @@ function cleanFunctionName(name: string): string {
   return name?.split('<')[0];
 }
 
+/**
+ * Escapes special regex characters in a string.
+ */
+function escapeRegExp(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Counts only DIRECT function calls, excluding method chains on return values.
+ *
+ * When a hook returns an object with methods that are later called, the analysis
+ * tracks those as call signatures like 'useAuth().functionCallReturnValue.signOut()'.
+ * These are NOT separate calls to useAuth - they're method invocations on the return value.
+ *
+ * This function filters out such method chains to get the true count of direct calls.
+ *
+ * @example
+ * // One direct call, one method on return value
+ * countDirectCalls(['useAuth()', 'useAuth().functionCallReturnValue.signOut()']) // => 1
+ *
+ * // Two direct calls
+ * countDirectCalls(['useFetcher()', 'useFetcher()']) // => 2
+ */
+function countDirectCalls(calls: string[]): number {
+  return calls.filter((sig) => !sig.includes('.functionCallReturnValue.'))
+    .length;
+}
+
+/**
+ * Checks if all direct calls (non-method-chain calls) are identical.
+ * This happens when destructuring a hook call:
+ *   const { authLoading, signOut } = useAuth();
+ * produces calls: ['useAuth()', 'useAuth()'] (same signature repeated)
+ *
+ * In this case, we should use the full unqualified schema since there's
+ * really only ONE function call, not multiple different calls.
+ *
+ * @example
+ * // Same call repeated (from destructuring)
+ * allDirectCallsIdentical(['useAuth()', 'useAuth()']) // => true
+ *
+ * // Different calls
+ * allDirectCallsIdentical(['useFetcher<User>()', 'useFetcher<Report>()']) // => false
+ *
+ * // Single call
+ * allDirectCallsIdentical(['useAuth()']) // => true
+ *
+ * // With method chain (method chain is ignored)
+ * allDirectCallsIdentical(['useAuth()', 'useAuth().functionCallReturnValue.signOut()']) // => true
+ */
+function allDirectCallsIdentical(calls: string[]): boolean {
+  const directCalls = calls.filter(
+    (sig) => !sig.includes('.functionCallReturnValue.'),
+  );
+  if (directCalls.length === 0) return true;
+  const firstCall = directCalls[0];
+  return directCalls.every((call) => call === firstCall);
+}
+
 /**
  * Preprocesses the schema to:
  * 1. Filter out all signature paths
@@ -68,6 +128,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 +150,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,29 +163,125 @@ 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 DISTINCT calls), OR
+  // 2. Single call with single variable name (directCallCount === 1 && varNamesLength === 1)
+  // Use base schema when:
+  // - Multiple calls that are all identical (destructuring case: const { a, b } = useHook())
+  // - directCallCount !== varNamesLength (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.
+  // Also important: method chains like useAuth().functionCallReturnValue.signOut() should NOT count
+  // as separate calls - only direct hook calls count.
+  const directCallCount = countDirectCalls(importedExport.calls ?? []);
+  const varNamesLength = importedExport.callVariableNames?.length ?? 0;
+  const shouldUseVariableQualifiedSchema =
+    variableNameOccurrence !== undefined ||
+    (directCallCount === 1 && varNamesLength === 1);
+  const variableName = shouldUseVariableQualifiedSchema
+    ? importedExport.callVariableNames?.[callIndex]
+    : undefined;
 
   // Build the schema lookup key - use variable-qualified key if available
-  const schemaLookupKey = variableName
-    ? `${importedExport.name}::${variableName}`
-    : importedExport.name;
+  // 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;
+
+  // Schema lookup order (most specific to least specific):
+  // 1. Call signature (e.g., 'useLoaderData<typeof loader>()')
+  // 2. Variable-qualified key with index (e.g., 'useFetcher::fetcher[1]')
+  // 3. Variable-qualified key without index (e.g., 'useFetcher::fetcher')
+  // 4. Base name (e.g., 'useLoaderData')
+
+  let rawSchema: Record<string, string> = {};
+
+  // 1. Try call signature first (most specific - new format)
+  if (callName !== importedExport.name) {
+    rawSchema =
+      dependencySchemas?.[importedExport.filePath]?.[callName]
+        ?.returnValueSchema ?? {};
+  }
+
+  // 2. Try variable-qualified key with index
+  if (Object.keys(rawSchema).length === 0 && indexedVariableName) {
+    const indexedKey = `${importedExport.name}::${indexedVariableName}`;
+    rawSchema =
+      dependencySchemas?.[importedExport.filePath]?.[indexedKey]
+        ?.returnValueSchema ?? {};
+  }
+
+  // 3. Try variable-qualified key without index (fallback for indexed lookup)
+  if (
+    Object.keys(rawSchema).length === 0 &&
+    variableNameOccurrence !== undefined &&
+    variableNameOccurrence > 0 &&
+    variableName
+  ) {
+    const nonIndexedKey = `${importedExport.name}::${variableName}`;
+    rawSchema =
+      dependencySchemas?.[importedExport.filePath]?.[nonIndexedKey]
+        ?.returnValueSchema ?? {};
+  }
 
-  const rawSchema =
-    dependencySchemas?.[importedExport.filePath]?.[schemaLookupKey]
+  // 4. Get base name schema and merge with call-specific schema
+  // The base schema often has more complete array element details that the
+  // call-specific schema might be missing. Instead of using as fallback only
+  // when empty, MERGE both schemas so we get the most complete picture.
+  //
+  // HOWEVER: For type-parameterized calls where the base schema contains paths
+  // from MULTIPLE DIFFERENT type parameters, DON'T merge to avoid contamination.
+  // The call-specific schema (rawSchema) is already isolated and complete.
+  const baseSchema =
+    dependencySchemas?.[importedExport.filePath]?.[importedExport.name]
       ?.returnValueSchema ?? {};
 
-  // If no schema found with variable-qualified key, fall back to base name
-  const fallbackSchema =
-    Object.keys(rawSchema).length === 0
-      ? (dependencySchemas?.[importedExport.filePath]?.[importedExport.name]
-          ?.returnValueSchema ?? {})
-      : rawSchema;
+  // Check if this is a type-parameterized call with a call-specific schema
+  const hasTypeParams = callName.includes('<') && callName.includes('>');
+  const hasCallSpecificSchema = Object.keys(rawSchema).length > 0;
+
+  // Check if the base schema has multiple DIFFERENT type parameter variants
+  // If so, merging would bring in wrong fields from other variants
+  let baseHasMultipleTypeParamVariants = false;
+  if (hasTypeParams && hasCallSpecificSchema) {
+    const baseFunctionName = cleanFunctionName(callName.split('(')[0]);
+    const typeParamVariantsInBase = new Set<string>();
+
+    for (const path of Object.keys(baseSchema)) {
+      // Look for paths like "useFetcher<TypeA>(...)" or "useFetcher<TypeB>(...)"
+      const match = path.match(
+        new RegExp(`^${escapeRegExp(baseFunctionName)}<([^>]+)>\\(`),
+      );
+      if (match) {
+        typeParamVariantsInBase.add(match[1]);
+      }
+    }
+    baseHasMultipleTypeParamVariants = typeParamVariantsInBase.size > 1;
+  }
+
+  // For type-parameterized calls where the base schema has MULTIPLE different type
+  // parameter variants, use ONLY the call-specific schema to avoid contamination.
+  // Otherwise, merge with base schema for complete coverage (e.g., array element details).
+  const mergedSchema =
+    hasCallSpecificSchema && hasTypeParams && baseHasMultipleTypeParamVariants
+      ? rawSchema // Use ONLY the call-specific schema when base has mixed type params
+      : Object.keys(rawSchema).length === 0
+        ? baseSchema
+        : { ...baseSchema, ...rawSchema };
 
   // Preprocess to filter signatures and extract functionCallReturnValue
-  let preprocessedSchema = preprocessSchemaForMocks(fallbackSchema);
+  let preprocessedSchema = preprocessSchemaForMocks(mergedSchema);
 
   const functionNames: string[] = [];
 
@@ -245,23 +415,11 @@ 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
-  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"
-    const disambiguator =
-      variableNameOccurrence !== undefined && variableNameOccurrence > 0
-        ? `[${variableNameOccurrence}]`
-        : '';
-    outputKey = `${variableName}${disambiguator} <- ${importedExport.name}`;
-  } else if (isObjectStyle) {
-    outputKey = importedExport.name;
-  } else {
-    outputKey = callName;
-  }
+  // Build output key - use the ORIGINAL CALL SIGNATURE from the code
+  // This makes it clear to the LLM exactly which call needs which data.
+  // Example: useFetcher<{ data: UserData }>() vs useFetcher<{ data: ReportData }>()
+  // Example: db.select(usersQuery) vs db.select(postsQuery)
+  const outputKey = callName;
 
   // Try to find return value - check with variable qualifier first, then without
   let returnValue = schema[schemaKey];
@@ -271,6 +429,49 @@ function processCall(
   if (!returnValue) {
     returnValue = schema['returnValue'];
   }
+  // Fallback for function call return values (e.g., useFetcher returns via functionCallReturnValue)
+  if (!returnValue) {
+    returnValue = schema['functionCallReturnValue'];
+  }
+
+  // Handle method-chain style calls (e.g., createClient().from("workouts").select("*") or db.select(query))
+  // After convertDotNotation, the schema is nested: { "createClient()": { "from(...)": { ... } } }
+  // We need to navigate the nested structure using the call signature parts.
+  // For object-style dependencies (isObjectStyle=true), the baseSchemaKey is just the object name (e.g., "db"),
+  // so returnValue might be the parent object, not the actual return value of the method chain.
+  // We should always try method-chain navigation for calls with dots and parens.
+  if (callName.includes('.') && callName.includes('(')) {
+    const callParts = splitOutsideParenthesesAndArrays(callName);
+    let current: unknown = schema;
+    for (const part of callParts) {
+      if (
+        current &&
+        typeof current === 'object' &&
+        !Array.isArray(current) &&
+        part in (current as Record<string, unknown>)
+      ) {
+        current = (current as Record<string, unknown>)[part];
+      } else {
+        current = undefined;
+        break;
+      }
+    }
+    // Use method-chain result if found, otherwise keep previous returnValue
+    if (current !== undefined) {
+      returnValue = current as typeof returnValue;
+      // Log when method-chain navigation succeeds for supabase-style calls
+      if (callName.includes('createClient') || callName.includes('from(')) {
+        console.log(
+          'CODEYAM: Method-chain navigation succeeded for:',
+          callName,
+          '-> keys:',
+          typeof returnValue === 'object' && returnValue
+            ? Object.keys(returnValue as object).slice(0, 5)
+            : typeof returnValue,
+        );
+      }
+    }
+  }
 
   if (!returnValue) {
     return null;
@@ -279,6 +480,27 @@ function processCall(
   return { key: outputKey, value: returnValue as JsonTypeDefinition };
 }
 
+/**
+ * Adds a result to the accumulator, merging schemas if the key already exists.
+ * This handles the case where the same call signature appears multiple times
+ * (e.g., two calls to useFetcher() with the same generic type).
+ */
+function addResultToAccumulator(
+  acc: { [key: string]: JsonTypeDefinition },
+  key: string,
+  value: JsonTypeDefinition,
+): void {
+  if (acc[key]) {
+    // Key already exists - merge the schemas
+    acc[key] = mergeJsonTypeDefinitions(
+      acc[key] as Record<string, unknown>,
+      value as Record<string, unknown>,
+    ) as JsonTypeDefinition;
+  } else {
+    acc[key] = value;
+  }
+}
+
 export default function gatherDataForMocks(
   importedExports: {
     filePath?: string;
@@ -288,19 +510,34 @@ 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;
 
-      // Check if we have multiple calls with variable names
-      const hasMultipleCalls =
-        importedExport.calls &&
-        importedExport.calls.length > 1 &&
+      // Get the clean hook name for indexing
+      const hookName = cleanFunctionName(importedExport.name);
+
+      // Check if we have multiple DISTINCT direct calls with variable names.
+      // Important: Only count direct calls to the function, not method chains on its return value.
+      // For example, ['useAuth()', 'useAuth().functionCallReturnValue.signOut()'] has only 1 direct call.
+      //
+      // ALSO: If all direct calls are IDENTICAL (same signature repeated), this is from
+      // destructuring like `const { a, b } = useHook()` and we should use the FULL unqualified
+      // schema, not iterate through partial variable-qualified schemas.
+      const directCallCount = countDirectCalls(importedExport.calls ?? []);
+      const hasMultipleDistinctCalls =
+        directCallCount > 1 &&
         importedExport.callVariableNames &&
-        importedExport.callVariableNames.length === importedExport.calls.length;
+        importedExport.callVariableNames.length === directCallCount &&
+        !allDirectCallsIdentical(importedExport.calls ?? []);
 
-      if (hasMultipleCalls) {
+      if (hasMultipleDistinctCalls) {
         // Track how many times each variable name has been seen
         // to disambiguate keys when the same variable is reused
         const variableNameCounts: Record<string, number> = {};
@@ -313,21 +550,129 @@ 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) {
+            addResultToAccumulator(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;
+        // Single calls, or multiple identical calls (from destructuring)
+        // Get the current hook call index and increment for next call
+        const hookCallIndex = hookCallIndices[hookName] ?? 0;
+        hookCallIndices[hookName] = hookCallIndex + 1;
+
+        // First, try to get result from unqualified schema
+        const processResult = processCall(
+          importedExport,
+          dependencySchemas,
+          0,
+          undefined,
+          options,
+          hookCallIndex,
+        );
+
+        // Check if we got a meaningful result (not empty object or null)
+        // Arrays are always meaningful (even empty ones represent valid data structure)
+        const hasUnqualifiedResult =
+          processResult &&
+          processResult.value !== null &&
+          (typeof processResult.value !== 'object' ||
+            Array.isArray(processResult.value) ||
+            Object.keys(processResult.value as object).length > 0);
+
+        // Check if we have multiple callVariableNames that are DIFFERENT
+        // (e.g., from parent + child components using the same hook differently)
+        // In this case, we should also merge in variable-qualified schemas
+        // to capture all destructured properties from both parent and child.
+        const uniqueCallVarNames = new Set(
+          importedExport.callVariableNames ?? [],
+        );
+        const hasDifferentVarNames =
+          importedExport.callVariableNames &&
+          importedExport.callVariableNames.length > 1 &&
+          uniqueCallVarNames.size > 1 &&
+          // Only merge variable-qualified schemas when calls are all identical
+          // (e.g., useFlags() repeated). Don't do this for method chains
+          // or rest spread cases where calls.length !== callVariableNames.length
+          allDirectCallsIdentical(importedExport.calls ?? []);
+
+        if (hasUnqualifiedResult) {
+          let finalValue = processResult.value;
+
+          // If we have different variable names (e.g., from parent and child components),
+          // also merge in variable-qualified schemas to ensure we capture all properties.
+          // This handles the case where parent uses useFlags().enableNewAdminDashboard
+          // and child uses useFlags().flagShowReferenceIdOnQuoteTable.
+          if (hasDifferentVarNames) {
+            let mergedValue = processResult.value as JsonTypeDefinition;
+            for (let i = 0; i < importedExport.callVariableNames!.length; i++) {
+              const varQualifiedResult = processCall(
+                importedExport,
+                dependencySchemas,
+                i,
+                0, // Use 0 to trigger variable-qualified lookup
+                options,
+                hookCallIndex,
+              );
+              if (varQualifiedResult && varQualifiedResult.value) {
+                mergedValue = mergeJsonTypeDefinitions(
+                  mergedValue as Record<string, unknown>,
+                  varQualifiedResult.value as Record<string, unknown>,
+                ) as JsonTypeDefinition;
+              }
+            }
+            finalValue = mergedValue;
+          }
+
+          addResultToAccumulator(
+            acc,
+            processResult.key,
+            finalValue as JsonTypeDefinition,
+          );
+        } else if (
+          directCallCount > 1 &&
+          allDirectCallsIdentical(importedExport.calls ?? []) &&
+          importedExport.callVariableNames &&
+          importedExport.callVariableNames.length > 0
+        ) {
+          // No unqualified schema exists, but we have multiple identical calls with variable names
+          // Merge all the variable-qualified schemas together
+          const callSignature =
+            importedExport.calls?.[0] ?? `${importedExport.name}()`;
+          let mergedValue: JsonTypeDefinition = {};
+
+          for (let i = 0; i < importedExport.callVariableNames.length; i++) {
+            const varQualifiedResult = processCall(
+              importedExport,
+              dependencySchemas,
+              i,
+              0, // Use 0 to trigger variable-qualified lookup
+              options,
+              hookCallIndex,
+            );
+            if (varQualifiedResult && varQualifiedResult.value) {
+              // Deep merge the value into the accumulated result
+              mergedValue = mergeJsonTypeDefinitions(
+                mergedValue,
+                varQualifiedResult.value,
+              );
+            }
+          }
+
+          if (Object.keys(mergedValue as object).length > 0) {
+            addResultToAccumulator(acc, callSignature, mergedValue);
+          }
         }
       }
 
@@ -335,4 +680,19 @@ export default function gatherDataForMocks(
     },
     {} as { [importAlias: string]: JsonTypeDefinition },
   );
+
+  // Log dataForMocks keys when supabase/createClient is involved
+  const supabaseKeys = Object.keys(result).filter(
+    (k) => k.includes('createClient') || k.includes('from('),
+  );
+  if (supabaseKeys.length > 0) {
+    console.log(
+      'CODEYAM: dataForMocks includes supabase keys:',
+      supabaseKeys,
+      '| All keys:',
+      Object.keys(result),
+    );
+  }
+
+  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) {