@codeyam/codeyam-cli 0.1.0-staging.bbe4da9 → 0.1.0-staging.d0ad4ae

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

@@ -16,7 +16,7 @@ import {
   updateFreshAnalysisStatus,
   upsertAnalyses,
   upsertEntities,
-} from '~codeyam/supabase';
+} from '~codeyam/database';
 import { getCandidatesReadyForCapture as getAnalysesReadyForCapture } from './dependencyResolver';
 import { awsLog, awsLogDebugLevel, Semaphore } from '~codeyam/utils';
 
@@ -376,6 +376,12 @@ export default async function analyzeEntities({
             // Circular dependency detected in path - skip
             continue;
           }
+          // If already visited via another traversal path, skip to avoid deadlock.
+          // Its subtree has been fully explored; any leaves are already in leafKeys.
+          // Blocking on it would just propagate the block and cause stuck analysis.
+          if (visited.has(dependentEntityKey)) {
+            continue;
+          }
           isLeaf = false;
           visitEntity(dependentEntity, [...path, dependentEntityKey]);
         }
@@ -499,7 +505,23 @@ export default async function analyzeEntities({
 
     const successfullyUpdated: Analysis[] = [];
 
+    console.log('CodeYam DEBUG: updateReadyAnalyses - newlyReady analyses:', {
+      count: newlyReady.length,
+      analyses: newlyReady.map((a) => ({
+        id: a.id,
+        filePath: a.filePath,
+        entityName: a.entityName,
+        scenarioCount: a.scenarios?.length ?? 0,
+      })),
+    });
+
     for (const analysis of newlyReady) {
+      console.log('CodeYam DEBUG: Setting readyToBeCaptured=true for:', {
+        id: analysis.id,
+        filePath: analysis.filePath,
+        entityName: analysis.entityName,
+      });
+
       const updatedStatus = await updateFreshAnalysisStatus(
         analysis.id!,
         (status) => {
@@ -511,6 +533,10 @@ export default async function analyzeEntities({
       if (updatedStatus) {
         analysis.status = updatedStatus;
         successfullyUpdated.push(analysis);
+        console.log('CodeYam DEBUG: Successfully marked readyToBeCaptured:', {
+          id: analysis.id,
+          entityName: analysis.entityName,
+        });
       } else {
         console.warn(
           `CodeYam: updateReadyAnalyses: Failed to update status for analysis ${analysis.id}`,

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

@@ -8,7 +8,7 @@ import {
   updateEntityBranch,
   upsertEntities,
   upsertEntityBranches,
-} from '~codeyam/supabase';
+} from '~codeyam/database';
 import getImportedExports from '../getImportedExports';
 import getNodeModuleImports from '../getNodeModuleImports';
 import { AnalysisContext } from '../../analysisContext';
@@ -161,6 +161,9 @@ export default async function findOrCreateEntity({
   const defaultExport = fileAnalyzer.isDefaultExport(entity.name);
   entity.metadata.namedExport = !defaultExport;
 
+  // Detect if the entity is an async function/component (Server Component in Next.js)
+  entity.metadata.isAsync = fileAnalyzer.isEntityAsync(localEntityName);
+
   if (defaultExport) {
     const allEntityNodes = fileAnalyzer.getAllEntityNodes();
     entity.metadata.exportAlias = Object.keys(allEntityNodes).find(

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

@@ -1,4 +1,4 @@
-import { loadMostRecentPreviousAnalysis } from '~codeyam/supabase';
+import { loadMostRecentPreviousAnalysis } from '~codeyam/database';
 import { Commit, Entity, File, Project } from '~codeyam/types';
 
 export interface FindValidExistingAnalysisArgs {

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

@@ -1,4 +1,4 @@
-import { loadAnalysis } from '~codeyam/supabase';
+import { loadAnalysis } from '~codeyam/database';
 import { Analysis, Project } from '~codeyam/types';
 
 export interface FindValidExistingAnalysisArgs {

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

@@ -3,6 +3,9 @@ import findOrCreateEntity from './findOrCreateEntity';
 import { ProjectAnalyzer } from '../../ProjectAnalyzer';
 import { AnalysisContext } from '../../analysisContext';
 
+// Track files we've already warned about to avoid duplicate warnings
+const warnedMissingFiles = new Set<string>();
+
 interface EntityWithGatheredDependencies extends Entity {
   dependenciesGathered?: boolean;
 }
@@ -79,9 +82,12 @@ export default async function gatherEntityMap({
       // 2. The original packages/types/errors.ts is never imported
       // 3. So it's not in getSourceFiles() and thus not in project.files
       // 4. Since the mock handles the import, we don't need to analyze the original
-      console.log(
-        `CodeYam Warning: Skipping dependency - file not in project.files (likely mocked): ${importedExportFilePath}`,
-      );
+      if (!warnedMissingFiles.has(importedExportFilePath)) {
+        warnedMissingFiles.add(importedExportFilePath);
+        console.log(
+          `CodeYam Warning: Skipping dependency - file not in project.files (likely mocked): ${importedExportFilePath}`,
+        );
+      }
       continue;
     }
 

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

@@ -2,7 +2,7 @@ import {
   loadAnalysisBranches,
   loadCommitBranches,
   upsertAnalysisBranches,
-} from '~codeyam/supabase';
+} from '~codeyam/database';
 import { Analysis, AnalysisBranch, Commit, Entity } from '~codeyam/types';
 import { awsLog } from '~codeyam/utils';
 

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

@@ -8,7 +8,7 @@ import generateDataStructure from './scenarios/generateDataStructure';
 import generateChangesScenarioData from './scenarios/generateChangesScenarioData';
 import generateChangesScenarios from './scenarios/generateChangesScenarios';
 import generateKeyAttributes from './scenarios/generateKeyAttributes';
-import { upsertAnalysesWithScenarios } from '~codeyam/supabase';
+import { upsertAnalysesWithScenarios } from '~codeyam/database';
 import { Step } from './enums/steps';
 import recordStep from './recordStep';
 import { FileAnalyzer } from '..';
@@ -22,6 +22,7 @@ import {
   pushAnalysisError,
   Semaphore,
 } from '~codeyam/utils';
+import deepEqual from '../utils/deepEqual';
 
 export interface AnalyzeChangeArgs {
   previousAnalysis: Analysis;
@@ -133,15 +134,30 @@ export default async function analyzeChange({
       analysis.status.steps.push(keyAttributesStep);
     }
 
-    if (
-      analysis.metadata.scenariosDataStructure ===
-      previousAnalysis.metadata.scenariosDataStructure
-    ) {
+    const dataStructureUnchanged = deepEqual(
+      analysis.metadata.scenariosDataStructure,
+      previousAnalysis.metadata.scenariosDataStructure,
+    );
+
+    const keyAttributesUnchanged = deepEqual(
+      analysis.metadata.keyAttributes,
+      previousAnalysis.metadata.keyAttributes,
+    );
+
+    if (dataStructureUnchanged && keyAttributesUnchanged) {
       awsLogDebugLevel(
         1,
-        `Data structure unchanged, reusing previous scenarios for ${entity.name}...`,
+        `Data structure and key attributes unchanged, reusing previous scenarios for ${entity.name}...`,
       );
-      analysis.scenarios = previousAnalysis.scenarios;
+      // Reuse previous scenarios but mark them for recapture if entity code changed
+      analysis.scenarios = previousAnalysis.scenarios.map((scenario) => ({
+        ...scenario,
+        metadata: {
+          ...scenario.metadata,
+          // Only mark for recapture if entity code actually changed
+          needsRecapture: entityChanged,
+        },
+      }));
     } else {
       if (!steps || steps.includes(Step.Scenarios)) {
         awsLogDebugLevel(1, `Generating scenarios for ${entity.name}...`);

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

@@ -2,7 +2,7 @@ import {
   deleteScenarios,
   upsertAnalysesWithScenarios,
   upsertEntities,
-} from '~codeyam/supabase';
+} from '~codeyam/database';
 import {
   AI,
   generateChangesEntityDocumentation,
@@ -271,13 +271,17 @@ export default async function analyzeEntity({
         });
       }
 
+      // Return early if analysis is already complete for its purpose:
+      // - Full analysis: has analyzedTreeSha
+      // - Dependency analysis: has keyAttributes (Structure + KeyAttributes already ran)
+      const isCompleteDependencyAnalysis =
+        analyzeAsDependency && !!existingAnalysis.metadata?.keyAttributes;
+
       if (
         !force &&
-        !!existingAnalysis.analyzedTreeSha &&
-        existingAnalysis.dependencyAnalyzedTreeSha === dependencyAnalyzedTreeSha //&&
-        // (existingAnalysis.status?.finishedAt ||
-        //   existingAnalysis.status?.readyToBeCaptured ||
-        //   branchCommitSha)
+        existingAnalysis.dependencyAnalyzedTreeSha ===
+          dependencyAnalyzedTreeSha &&
+        (!!existingAnalysis.analyzedTreeSha || isCompleteDependencyAnalysis)
       ) {
         awsLogDebugLevel(1, `Using existing analysis for ${entity.name}...`);
         awsLog('Returning existing analysis', {

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

@@ -11,7 +11,7 @@ import {
   type Entity,
   type ReadonlyAnalysisMap,
 } from '~codeyam/types';
-import { upsertAnalysesWithScenarios } from '~codeyam/supabase';
+import { upsertAnalysesWithScenarios } from '~codeyam/database';
 import {
   awsLog,
   awsLogDebugLevel,

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

@@ -1,6 +1,6 @@
 import { Entity, EntityType, File, ProjectFramework } from '~codeyam/types';
 import { ProjectAnalyzer } from '../ProjectAnalyzer';
-import { generateSha } from '~codeyam/supabase';
+import { generateSha } from '~codeyam/database';
 import { isNextRoute } from '~codeyam/utils';
 
 export default function analyzeNextRoute(

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

@@ -1,6 +1,6 @@
 import { Entity, EntityType, File, ProjectFramework } from '~codeyam/types';
 import { ProjectAnalyzer } from '../ProjectAnalyzer';
-import { generateSha } from '~codeyam/supabase';
+import { generateSha } from '~codeyam/database';
 import { isRemixRoute } from '~codeyam/utils';
 
 export default function analyzeRemixRoute(

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

@@ -2,7 +2,7 @@ import { Entity, File, Project } from '~codeyam/types';
 import { FileAnalyzer } from '../FileAnalyzer';
 import { ProjectAnalyzer } from '../ProjectAnalyzer';
 import type { FunctionDependenciesMap } from '../asts/sourceFiles/getPseudoFile';
-// import { generateSha } from '~codeyam/supabase';
+// import { generateSha } from '~codeyam/database';
 
 export default function getImportedExports(
   file: File,
@@ -73,19 +73,43 @@ export default function getImportedExports(
         // Workspace packages often resolve to dist/ paths (from package.json "types" or "main"),
         // but our project.files contains source files in src/. Try mapping dist -> src.
         if (!importedExportFile && searchPath.includes('/dist/')) {
-          const srcPath = searchPath.replace('/dist/', '/src/');
-          // Try exact match first
-          importedExportFile = project.files.find((f) => f.path === srcPath);
-          if (importedExportFile) {
-            actualResolvedPath = srcPath;
-            console.log(
-              `CodeYam: Mapped dist->src path: ${searchPath} -> ${srcPath}`,
-            );
+          // Some build tools create nested structures like dist/packageName/src/file.d.ts
+          // when the source is at packages/packageName/src/file.ts
+          // Pattern: packages/X/dist/X/src/Y -> packages/X/src/Y
+          const nestedDistMatch = searchPath.match(
+            /^(packages\/[^/]+)\/dist\/[^/]+\/src\/(.+)$/,
+          );
+          if (nestedDistMatch) {
+            const [, packagePath, relativePath] = nestedDistMatch;
+            const srcPath = `${packagePath}/src/${relativePath}`
+              .replace(/\.d\.ts$/, '.ts')
+              .replace(/\.js$/, '.ts');
+            importedExportFile = project.files.find((f) => f.path === srcPath);
+            if (importedExportFile) {
+              actualResolvedPath = srcPath;
+              console.log(
+                `CodeYam: Mapped nested dist->src path: ${searchPath} -> ${srcPath}`,
+              );
+            }
+          }
+
+          // Try simple dist -> src replacement if nested pattern didn't match
+          if (!importedExportFile) {
+            const srcPath = searchPath.replace('/dist/', '/src/');
+            // Try exact match first
+            importedExportFile = project.files.find((f) => f.path === srcPath);
+            if (importedExportFile) {
+              actualResolvedPath = srcPath;
+              console.log(
+                `CodeYam: Mapped dist->src path: ${searchPath} -> ${srcPath}`,
+              );
+            }
           }
 
           // If not found, the dist file might be index.d.ts but src might be index.ts
           // or the export might be re-exported from another file
           if (!importedExportFile) {
+            const srcPath = searchPath.replace('/dist/', '/src/');
             // Try removing .d.ts extension and finding any matching src file
             const basePath = srcPath
               .replace(/\.d\.ts$/, '')
@@ -107,40 +131,48 @@ export default function getImportedExports(
         }
 
         if (!importedExportFile) {
-          // Check if this is a workspace package import (scoped npm package like @scope/package)
-          // but NOT a path alias like @/path or @components/...
-          // Scoped packages have format: @scope/package where scope is alphanumeric with hyphens
-          const isScopedPackage =
-            filePath.startsWith('@') &&
-            !filePath.startsWith('@/') && // Not a path alias like @/modules/...
-            !filePath.startsWith('@types/') &&
-            /^@[a-z0-9-]+\/[a-z0-9-]/.test(filePath); // Matches @scope/package pattern
-          if (isScopedPackage) {
-            // Treat unresolved scoped packages like node modules so they get mocked
-            // instead of being silently ignored
+          // Check if this looks like a path alias (starts with @/ or similar patterns)
+          // Path aliases should resolve to project files - if they don't, it's a config issue
+          // Also check for ~packageName/ patterns like ~codeyam/supabase
+          const isPathAlias =
+            filePath.startsWith('@/') ||
+            filePath.startsWith('~/') ||
+            filePath.startsWith('#/') ||
+            /^~[a-zA-Z]/.test(filePath); // ~packageName patterns like ~codeyam/
+
+          const name =
+            importedExportInfo.importName ?? importedExportInfo.importAlias;
+
+          if (isPathAlias) {
+            // Path aliases should resolve - if they don't, it's a configuration issue
+            // Don't treat as node module, just log and skip
+            console.log(
+              'CodeYam Warning: Path alias import not resolved (file may be missing or path alias misconfigured):',
+              file.path,
+              filePath,
+              importedExportInfo,
+            );
+            return;
+          }
+
+          // If still not found, track as unresolved import
+          // Don't set isMocked here - let later processing determine based on mockedDependencies
+          // This ensures the import is tracked (not dropped) while deferring the mocking decision
+          if (!importedExportFile) {
             const name =
               importedExportInfo.importName ?? importedExportInfo.importAlias;
             console.log(
-              `CodeYam: Treating unresolved scoped package as node module: ${filePath} -> ${name}`,
+              `CodeYam: Tracking unresolved import (mocking decision deferred): ${filePath} -> ${name}`,
             );
             return {
               filePath,
               name,
               isDefault: importedExportInfo.isImportDefault,
-              isNodeModule: true, // Mark as node module so it gets mocked
-              entityType: 'library' as const, // Default to library since we can't determine the actual type
-              // No code since we couldn't resolve the source file
+              // isMocked intentionally undefined - will be determined later by prepareDataStructures
+              // based on mockedDependencies analysis
+              entityType: 'library' as const,
             };
-          } else {
-            console.log(
-              'CodeYam Error: File not found for imported export',
-              file.path,
-              filePath,
-              importedExportInfo,
-              imports[filePath],
-            );
           }
-          return;
         }
 
         try {
@@ -156,9 +188,29 @@ export default function getImportedExports(
           const name =
             importedExportInfo.importName ?? importedExportInfo.importAlias;
 
-          const resolvedFilePath = importedExportInfo.resolvedPath;
+          // Map nested dist paths in resolvedPath to src paths
+          // Pattern: packages/X/dist/X/src/Y -> packages/X/src/Y
+          let resolvedFilePath = importedExportInfo.resolvedPath;
+          if (resolvedFilePath) {
+            const nestedDistMatch = resolvedFilePath.match(
+              /^(packages\/[^/]+)\/dist\/[^/]+\/src\/(.+)$/,
+            );
+            if (nestedDistMatch) {
+              const [, packagePath, relativePath] = nestedDistMatch;
+              resolvedFilePath = `${packagePath}/src/${relativePath}`
+                .replace(/\.d\.ts$/, '.ts')
+                .replace(/\.js$/, '.ts');
+            }
+          }
           const resolvedName = importedExportInfo.exportName;
 
+          // When a default export is re-exported as named (e.g., `export { default as X }`),
+          // isExportDefault will be false (it's exported as named from the barrel),
+          // but resolvedName will be 'default'. In this case, we need resolvedIsDefault
+          // to be true so that writeScenarioComponents adds the named re-export.
+          const resolvedIsDefault =
+            importedExportInfo.isExportDefault || resolvedName === 'default';
+
           return {
             fileId: importedExportFile.id,
             filePath: actualResolvedPath,
@@ -168,7 +220,7 @@ export default function getImportedExports(
                 ? undefined
                 : resolvedFilePath,
             resolvedName: resolvedName === name ? undefined : resolvedName,
-            resolvedIsDefault: importedExportInfo.isExportDefault,
+            resolvedIsDefault,
             entityType,
             name,
             code,

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

@@ -0,0 +1,196 @@
+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
+  // We check both direct imports AND all schemas in dependencySchemas because
+  // transitive dependencies (e.g., SurveyCard imported by SurveysList imported by SurveysPage)
+  // may have signature schemas that we need to use for enrichment.
+  const childSignatureFields: {
+    filePath: string;
+    entityName: string;
+    // Map of prop paths to types, e.g., { "survey.id": "string", "survey.updatedAt": "date" }
+    propFields: Record<string, string>;
+  }[] = [];
+
+  // Helper to extract prop fields from a signature schema
+  const extractPropFields = (
+    schema: Record<string, string>,
+  ): Record<string, string> => {
+    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 [, , fieldPath] = match;
+        // Store as "fieldPath" without the prop name prefix
+        // e.g., signature[0].survey.updatedAt -> updatedAt
+        propFields[fieldPath] = type;
+      }
+    }
+    return propFields;
+  };
+
+  // First, check direct imports (non-mocked)
+  const processedSchemas = new Set<string>();
+  for (const importedExport of importedExports) {
+    // Skip mocked dependencies - we want child components
+    if (importedExport.isMocked || !importedExport.filePath) continue;
+
+    const schemaKey = `${importedExport.filePath}::${importedExport.name}`;
+    processedSchemas.add(schemaKey);
+
+    const schema =
+      dependencySchemas?.[importedExport.filePath]?.[importedExport.name]
+        ?.signatureSchema;
+    if (!schema) continue;
+
+    const propFields = extractPropFields(schema);
+    if (Object.keys(propFields).length > 0) {
+      childSignatureFields.push({
+        filePath: importedExport.filePath,
+        entityName: importedExport.name,
+        propFields,
+      });
+    }
+  }
+
+  // Also check all schemas in dependencySchemas for transitive child components
+  // that may not be in importedExports but have signature schemas with prop fields
+  if (dependencySchemas) {
+    for (const [filePath, entities] of Object.entries(dependencySchemas)) {
+      for (const [entityName, schemas] of Object.entries(entities)) {
+        const schemaKey = `${filePath}::${entityName}`;
+        // Skip already processed schemas
+        if (processedSchemas.has(schemaKey)) continue;
+
+        const signatureSchema = schemas?.signatureSchema;
+        if (!signatureSchema) continue;
+
+        const propFields = extractPropFields(signatureSchema);
+        if (Object.keys(propFields).length > 0) {
+          childSignatureFields.push({
+            filePath,
+            entityName,
+            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;
+        }
+      }
+    }
+  }
+}