@codeyam/codeyam-cli 0.1.0-staging.323686 → 0.1.0-staging.483fdc2

package/analyzer-template/packages/analyze/src/lib/asts/sourceFiles/getImportsAnalysis.ts

@@ -6,7 +6,14 @@ type ImportsAnalysis = {
   [importedFilePath: string]: ExportInfo[];
 };
 
+const importsAnalysisCache = new WeakMap<ts.SourceFile, ImportsAnalysis>();
+
 export function getImportsAnalysis(sourceFile: ts.SourceFile): ImportsAnalysis {
+  const cached = importsAnalysisCache.get(sourceFile);
+  if (cached) {
+    return cached;
+  }
+
   const importsMapEntries: [string, ExportInfo[]][] = [];
 
   const importsVisitor = (node: ts.Node) => {
@@ -35,6 +42,7 @@ export function getImportsAnalysis(sourceFile: ts.SourceFile): ImportsAnalysis {
     {} as ImportsAnalysis,
   );
 
+  importsAnalysisCache.set(sourceFile, consolidatedImportsMapEntries);
   return consolidatedImportsMapEntries;
 }
 

package/analyzer-template/packages/analyze/src/lib/asts/sourceFiles/getResolvedModule.ts

@@ -2,21 +2,44 @@ import ts from 'typescript';
 import path from 'path';
 import fs from 'fs';
 
+/**
+ * Cache for nearest tsconfig lookups (keyed by directory).
+ * Speeds up repeated lookups during module resolution.
+ */
+const nearestTsConfigCache = new Map<string, string | undefined>();
+
 /**
  * Find the nearest tsconfig.json by walking up the directory tree from the source file
  */
 function findNearestTsConfig(sourceFileName: string): string | undefined {
   let currentDir = path.dirname(sourceFileName);
   const root = path.parse(currentDir).root;
+  const visited: string[] = [];
 
   while (currentDir !== root) {
+    const cached = nearestTsConfigCache.get(currentDir);
+    if (cached !== undefined || nearestTsConfigCache.has(currentDir)) {
+      for (const dir of visited) {
+        nearestTsConfigCache.set(dir, cached);
+      }
+      return cached;
+    }
+
+    visited.push(currentDir);
     const tsConfigPath = path.join(currentDir, 'tsconfig.json');
     if (fs.existsSync(tsConfigPath)) {
+      for (const dir of visited) {
+        nearestTsConfigCache.set(dir, tsConfigPath);
+      }
       return tsConfigPath;
     }
     currentDir = path.dirname(currentDir);
   }
 
+  for (const dir of visited) {
+    nearestTsConfigCache.set(dir, undefined);
+  }
+
   return undefined;
 }
 
@@ -25,6 +48,14 @@ function findNearestTsConfig(sourceFileName: string): string | undefined {
  */
 const tsConfigCache = new Map<string, ts.CompilerOptions>();
 
+/**
+ * Cache resolved module lookups by program for fast repeat access.
+ */
+const resolvedModuleCacheByProgram = new WeakMap<
+  ts.Program,
+  Map<string, ts.ResolvedModuleFull | null>
+>();
+
 /**
  * Get compiler options from a tsconfig file
  */
@@ -62,6 +93,19 @@ export function getResolvedModule(
   // Try to find the nearest tsconfig for this source file
   const nearestTsConfig = findNearestTsConfig(sourceFile.fileName);
 
+  const cacheForProgram =
+    resolvedModuleCacheByProgram.get(program) ??
+    new Map<string, ts.ResolvedModuleFull | null>();
+  if (!resolvedModuleCacheByProgram.has(program)) {
+    resolvedModuleCacheByProgram.set(program, cacheForProgram);
+  }
+
+  const cacheKey = `${nearestTsConfig ?? ''}|${sourceFile.fileName}|${moduleName}`;
+  if (cacheForProgram.has(cacheKey)) {
+    const cached = cacheForProgram.get(cacheKey);
+    return cached ?? undefined;
+  }
+
   // Start with the program's compiler options
   let compilerOptions = program.getCompilerOptions();
 
@@ -90,6 +134,7 @@ export function getResolvedModule(
 
   // If TypeScript's resolution succeeded, return it
   if (result.resolvedModule) {
+    cacheForProgram.set(cacheKey, result.resolvedModule);
     return result.resolvedModule;
   }
 
@@ -105,14 +150,17 @@ export function getResolvedModule(
     for (const ext of extensions) {
       const testPath = absolutePath + ext;
       if (fs.existsSync(testPath)) {
-        return {
+        const resolved = {
           resolvedFileName: testPath,
           extension: ext.includes('/') ? path.extname(ext) : ext,
           isExternalLibraryImport: false,
         } as ts.ResolvedModuleFull;
+        cacheForProgram.set(cacheKey, resolved);
+        return resolved;
       }
     }
   }
 
+  cacheForProgram.set(cacheKey, null);
   return undefined;
 }

package/analyzer-template/packages/analyze/src/lib/asts/sourceFiles/getSourceFilesForAllImports.ts

@@ -21,5 +21,6 @@ export function getSourceFilesForAllImports(
 
   visit(sourceFile); // Start visiting nodes from the root source file
 
-  return getSourceFilesForImports(moduleNames, sourceFile, program);
+  const uniqueModuleNames = Array.from(new Set(moduleNames));
+  return getSourceFilesForImports(uniqueModuleNames, sourceFile, program);
 }

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

@@ -336,11 +336,23 @@ async function getEntityDataStructureAndFunctionCalls({
         functionName: importedExport.name,
       });
 
-      // If neither signature nor return value found, this function doesn't exist in the analysis.
-      // We need to check BOTH because hooks like useParams() have no signature (no arguments)
-      // but DO have a return value that needs to be mocked.
+      // If neither signature nor return value found, check if this function has matching
+      // external function calls. External functions (like useLoaderData from react-router)
+      // don't have entries in functionResults, so getReturnValue returns null for them.
+      // But their return values ARE traced in externalFunctionCalls via perVariableSchemas.
+      // We need to check for matching calls before skipping.
       if (!signatureSchema && !returnValueSchema) {
-        return acc;
+        const hasMatchingExternalCall =
+          dataStructure.externalFunctionCalls?.some(
+            (fc) =>
+              fc.name === importedExport.name ||
+              fc.name.startsWith(importedExport.name + '<'),
+          );
+
+        // Only skip if there are no matching external function calls
+        if (!hasMatchingExternalCall) {
+          return acc;
+        }
       }
 
       // Clone schemas before deduplication to avoid mutating shared references
@@ -570,11 +582,13 @@ async function getEntityDataStructureAndFunctionCalls({
   // Get JSX rendering usages for array size and text length flow generation
   const jsxRenderingUsages = getJsxRenderingUsages(dataStructure);
 
+  const equivalentSignatureVariables =
+    getEquivalentSignatureVariables(dataStructure);
+
   const isolatedDataStructure = {
     signatureSchema: deduplicateFunctionSchemas(clonedRawSignature),
     returnValueSchema: deduplicateFunctionSchemas(clonedRawReturnValue),
-    equivalentSignatureVariables:
-      getEquivalentSignatureVariables(dataStructure),
+    equivalentSignatureVariables,
     dependencySchemas,
     environmentVariables: dataStructure.environmentVariables,
     conditionalUsages:

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

@@ -5,6 +5,7 @@ import {
   measureAndReportExecutionTime,
   ProjectAnalyzer,
 } from '~codeyam/analyze';
+import { getFileByPathSafe } from '../../utils/getFileByPath';
 import trackEntityCircularDependencies from './trackEntityCircularDependencies';
 import validateDependencyAnalyses from './validateDependencyAnalyses';
 import extractClassMethods from './analyzeEntities/extractClassMethods';
@@ -388,10 +389,19 @@ 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 already visited via another traversal path, check if it's a leaf.
+          // If it's a leaf, we should still wait for it to complete.
+          // Only skip if we've already explored it and it's NOT a leaf (meaning it's
+          // blocked on something else - continuing to traverse would cause a deadlock).
           if (visited.has(dependentEntityKey)) {
+            // If the visited entity is a leaf, we should wait for it to complete
+            // before processing this entity. Don't skip it!
+            if (leafKeys.has(dependentEntityKey)) {
+              // It's a leaf that hasn't completed yet - wait for it
+              isLeaf = false;
+              continue;
+            }
+            // If it's not a leaf, it's blocked on something else - skip to avoid deadlock
             continue;
           }
           isLeaf = false;
@@ -426,7 +436,7 @@ export default async function analyzeEntities({
     }
 
     const file =
-      entity.file || project.files.find((f) => f.path === entity.filePath);
+      entity.file || getFileByPathSafe(projectAnalyzer, entity.filePath);
     if (!file) {
       awsLog(
         `CodeYam: analyzeEntities: File not found for entity: ${entityKey}`,

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

@@ -1,6 +1,7 @@
 import { Entity } from '~codeyam/types';
 import findOrCreateEntity from './findOrCreateEntity';
 import { ProjectAnalyzer } from '../../ProjectAnalyzer';
+import { getFileByPathSafe } from '../../utils/getFileByPath';
 import { AnalysisContext } from '../../analysisContext';
 
 // Track files we've already warned about to avoid duplicate warnings
@@ -71,8 +72,9 @@ export default async function gatherEntityMap({
     //   `  → imported export ${importedExportFilePath}:${importedExportName}`,
     // );
 
-    const importedFile = project.files.find(
-      (file) => file.path === importedExportFilePath,
+    const importedFile = getFileByPathSafe(
+      projectAnalyzer,
+      importedExportFilePath,
     );
 
     if (!importedFile) {

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

@@ -69,9 +69,6 @@ export default function validateDependencyAnalyses({
 
     // if the entity has duplicate dependencies, handle gracefully
     if (dependentAnalyses[dependencyFilePath]?.[dependencyName]) {
-      // console.log(
-      //   `CodeYam: validateDependencyAnalyses: Entity ${entity.filePath}:${entity.name} has duplicate dependency ${dependencyFilePath}:${dependencyName}. Skipping...`,
-      // );
       continue;
     }
 

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

@@ -1,5 +1,6 @@
 import { Entity, EntityType, File, ProjectFramework } from '~codeyam/types';
 import { ProjectAnalyzer } from '../ProjectAnalyzer';
+import { getFileByPathSafe } from '../utils/getFileByPath';
 import { generateSha } from '~codeyam/database';
 import { isRemixRoute } from '~codeyam/utils';
 
@@ -88,11 +89,9 @@ export default function analyzeRemixRoute(
   // Find root.tsx for this route's webapp and add as implicit dependency
   // This ensures root.tsx dependencies (like useLoaderData in AppContent) get analyzed for mocking
   const routeAppDir = file.path.split('/routes/')[0];
-  const rootFile = projectAnalyzer.project.files.find(
-    (f) =>
-      f.path === `${routeAppDir}/root.tsx` ||
-      f.path === `${routeAppDir}/root.jsx`,
-  );
+  const rootFile =
+    getFileByPathSafe(projectAnalyzer, `${routeAppDir}/root.tsx`) ??
+    getFileByPathSafe(projectAnalyzer, `${routeAppDir}/root.jsx`);
 
   const rootDependencies: Entity['metadata']['importedExports'] = [];
   if (rootFile) {

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

@@ -1,6 +1,7 @@
 import { Entity, File, Project } from '~codeyam/types';
 import { FileAnalyzer } from '../FileAnalyzer';
 import { ProjectAnalyzer } from '../ProjectAnalyzer';
+import { getFileByPathSafe } from '../utils/getFileByPath';
 import type { FunctionDependenciesMap } from '../asts/sourceFiles/getPseudoFile';
 // import { generateSha } from '~codeyam/database';
 
@@ -63,9 +64,7 @@ export default function getImportedExports(
           imports[filePath].resolvedPath ??
           filePath;
 
-        let importedExportFile = project.files.find(
-          (f) => f.path === searchPath,
-        );
+        let importedExportFile = getFileByPathSafe(projectAnalyzer, searchPath);
 
         // Track the actual path we found (may differ from searchPath after dist->src mapping)
         let actualResolvedPath = imports[filePath].resolvedPath;
@@ -84,7 +83,7 @@ export default function getImportedExports(
             const srcPath = `${packagePath}/src/${relativePath}`
               .replace(/\.d\.ts$/, '.ts')
               .replace(/\.js$/, '.ts');
-            importedExportFile = project.files.find((f) => f.path === srcPath);
+            importedExportFile = getFileByPathSafe(projectAnalyzer, srcPath);
             if (importedExportFile) {
               actualResolvedPath = srcPath;
               console.log(
@@ -97,7 +96,7 @@ export default function getImportedExports(
           if (!importedExportFile) {
             const srcPath = searchPath.replace('/dist/', '/src/');
             // Try exact match first
-            importedExportFile = project.files.find((f) => f.path === srcPath);
+            importedExportFile = getFileByPathSafe(projectAnalyzer, srcPath);
             if (importedExportFile) {
               actualResolvedPath = srcPath;
               console.log(
@@ -114,13 +113,16 @@ export default function getImportedExports(
             const basePath = srcPath
               .replace(/\.d\.ts$/, '')
               .replace(/\.js$/, '');
-            importedExportFile = project.files.find(
-              (f) =>
-                f.path === basePath + '.ts' ||
-                f.path === basePath + '.tsx' ||
-                (f.path.startsWith(basePath.replace('/index', '/')) &&
-                  !f.path.includes('/dist/')),
-            );
+            importedExportFile =
+              getFileByPathSafe(projectAnalyzer, basePath + '.ts') ??
+              getFileByPathSafe(projectAnalyzer, basePath + '.tsx');
+            if (!importedExportFile) {
+              importedExportFile = project.files.find(
+                (f) =>
+                  f.path.startsWith(basePath.replace('/index', '/')) &&
+                  !f.path.includes('/dist/'),
+              );
+            }
             if (importedExportFile) {
               actualResolvedPath = importedExportFile.path;
               console.log(

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

@@ -101,27 +101,47 @@ export default function enrichArrayTypesFromChildSignatures(
   ): void => {
     // Group by prop name (e.g., signature[0].survey.id, signature[0].survey.name -> "survey")
     const propGroups: Record<string, Record<string, string>> = {};
+    // Also collect direct fields on signature[0] (e.g., signature[0].filePath -> "filePath")
+    const directFields: Record<string, string> = {};
 
     for (const [path, type] of Object.entries(schema)) {
       // Match signature[0].propName.field or signature[0].propName[].field patterns
       // The (?:\[\])? makes array props optional, handling both:
       // - signature[0].survey.updatedAt (object prop)
       // - signature[0].questionAnswers[].question.questionText (array prop)
-      const match = path.match(/^signature\[0\]\.(\w+)(?:\[\])?\.(.+)$/);
-      if (match) {
-        const [, propName, fieldPath] = match;
+      const nestedMatch = path.match(/^signature\[0\]\.(\w+)(?:\[\])?\.(.+)$/);
+      if (nestedMatch) {
+        const [, propName, fieldPath] = nestedMatch;
         propGroups[propName] ||= {};
         propGroups[propName][fieldPath] = type;
+        continue;
+      }
+
+      // Also match direct fields: signature[0].fieldName (single level, no nested path)
+      // This handles cases like TruncatedFilePath where filePath is passed directly
+      const directMatch = path.match(/^signature\[0\]\.(\w+)$/);
+      if (directMatch) {
+        const [, fieldName] = directMatch;
+        directFields[fieldName] = type;
       }
     }
 
-    // Store with the full signature path as key
+    // Store nested prop groups with the full signature path as key
     for (const [propName, fields] of Object.entries(propGroups)) {
       if (Object.keys(fields).length > 0) {
         const signaturePath = `${entityName}().signature[0].${propName}`;
         childSignatureFieldsByPath.set(signaturePath, { propName, fields });
       }
     }
+
+    // Store direct fields with signature[0] as key (for when entire object is passed)
+    if (Object.keys(directFields).length > 0) {
+      const signaturePath = `${entityName}().signature[0]`;
+      childSignatureFieldsByPath.set(signaturePath, {
+        propName: '',
+        fields: directFields,
+      });
+    }
   };
 
   // Process all schemas in dependencySchemas
@@ -187,15 +207,20 @@ export default function enrichArrayTypesFromChildSignatures(
   for (const { filePath, entityName, arrayPath } of mockedArrayPaths) {
     const schema = dependencySchemas[filePath][entityName].returnValueSchema;
 
-    // Check if this array already has element type definitions
+    // Check if this array already has INDEXED element type definitions (e.g., [0]: null)
     // If so, skip it - it's likely a specialized array like [null] for refs
+    // But DON'T skip if it only has general [] element types - those can be enriched
     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)
+    const hasIndexedElementType = Object.keys(schema).some((path) => {
+      if (!path.startsWith(elementPathPrefix)) return false;
+      // Check if it's an indexed type like [0], [1], etc. vs general []
+      const afterPrefix = path.slice(elementPathPrefix.length);
+      // Indexed types start with a digit: [0], [1], etc.
+      return /^\d/.test(afterPrefix);
+    });
+
+    if (hasIndexedElementType) {
+      // Array already has indexed element type info (e.g., useAutoAnimate()[0]: null)
       // Don't override it with child signature fields
       continue;
     }
@@ -218,7 +243,13 @@ export default function enrichArrayTypesFromChildSignatures(
 
         // Check if this local variable could have come from this mocked function
         // Use heuristics: name matching (getSurveys -> surveys, getUsers -> users)
-        if (!couldBeDerivedFrom(localVarName, entityName)) {
+        // Also check if the array path ends with the local variable name
+        // e.g., useLoaderData().functionCallReturnValue.entities ends with .entities
+        const arrayEndsWithLocalVar = arrayPath.endsWith(`.${localVarName}`);
+        if (
+          !couldBeDerivedFrom(localVarName, entityName) &&
+          !arrayEndsWithLocalVar
+        ) {
           continue;
         }
 
@@ -257,8 +288,21 @@ export default function enrichArrayTypesFromChildSignatures(
 
     for (const [fieldPath, type] of Object.entries(matchedFields)) {
       const fullPath = `${elementPath}.${fieldPath}`;
-      if (!schema[fullPath]) {
+      const existingType = schema[fullPath];
+      if (!existingType) {
         schema[fullPath] = type;
+      } else {
+        // Prefer the more specific (narrower) type
+        const existingIsOptional =
+          existingType.includes('| undefined') ||
+          existingType.includes('| null');
+        const newIsOptional =
+          type.includes('| undefined') || type.includes('| null');
+        if (existingIsOptional && !newIsOptional) {
+          // Use the new type - it's more specific
+          schema[fullPath] = type;
+        }
+        // Otherwise keep existing (same specificity or existing is more specific)
       }
     }
   }

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

@@ -1,6 +1,8 @@
 import {
   convertDotNotation,
   fillInDirectSchemaGapsAndUnknowns,
+  buildSchemaIndexes,
+  type SchemaIndexes,
   joinParenthesesAndArrays,
   mergeJsonTypeDefinitions,
   splitOutsideParenthesesAndArrays,
@@ -165,6 +167,7 @@ function processCall(
   variableNameOccurrence: number | undefined,
   options: GatherDataForMocksOptions | undefined,
   hookCallIndex: number,
+  prebuiltIndexes?: SchemaIndexes,
 ): { key: string; value: JsonTypeDefinition } | null {
   const callName = importedExport.calls?.[callIndex] ?? importedExport.name;
 
@@ -465,6 +468,7 @@ function processCall(
   const filledSchema = fillInDirectSchemaGapsAndUnknowns({
     scopeName: importedExport.name,
     schema: relevantMergedDependencySchema,
+    prebuiltIndexes,
   });
 
   const schema = convertDotNotation(filledSchema);
@@ -568,6 +572,25 @@ export default function gatherDataForMocks(
   dependencySchemas: DataStructure['dependencySchemas'],
   options?: GatherDataForMocksOptions,
 ) {
+  // Build schema indexes ONCE from all dependency schemas combined.
+  // This avoids rebuilding indexes (~1-2 seconds for 18k keys) for each processCall.
+  const allSchemaKeys: Record<string, string> = {};
+  if (dependencySchemas) {
+    for (const filePath in dependencySchemas) {
+      for (const entityName in dependencySchemas[filePath]) {
+        const schema =
+          dependencySchemas[filePath][entityName]?.returnValueSchema;
+        if (schema) {
+          Object.assign(allSchemaKeys, schema);
+        }
+      }
+    }
+  }
+  const prebuiltIndexes =
+    Object.keys(allSchemaKeys).length > 0
+      ? buildSchemaIndexes(allSchemaKeys)
+      : undefined;
+
   // 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> = {};
@@ -653,6 +676,7 @@ export default function gatherDataForMocks(
             undefined,
             options,
             hookCallIndex,
+            prebuiltIndexes,
           );
 
           if (processResult) {
@@ -717,6 +741,7 @@ export default function gatherDataForMocks(
             occurrence,
             options,
             hookCallIndex,
+            prebuiltIndexes,
           );
           if (processResult) {
             addResultToAccumulator(acc, processResult.key, processResult.value);
@@ -749,6 +774,7 @@ export default function gatherDataForMocks(
             undefined,
             options,
             hookCallIndex,
+            prebuiltIndexes,
           );
 
           if (processResult) {
@@ -769,6 +795,7 @@ export default function gatherDataForMocks(
           undefined,
           options,
           hookCallIndex,
+          prebuiltIndexes,
         );
 
         // Check if we got a meaningful result (not empty object or null)
@@ -813,6 +840,7 @@ export default function gatherDataForMocks(
                 0, // Use 0 to trigger variable-qualified lookup
                 options,
                 hookCallIndex,
+                prebuiltIndexes,
               );
               if (varQualifiedResult && varQualifiedResult.value) {
                 mergedValue = mergeJsonTypeDefinitions(
@@ -849,6 +877,7 @@ export default function gatherDataForMocks(
               0, // Use 0 to trigger variable-qualified lookup
               options,
               hookCallIndex,
+              prebuiltIndexes,
             );
             if (varQualifiedResult && varQualifiedResult.value) {
               // Deep merge the value into the accumulated result

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

@@ -16,6 +16,7 @@ import { awsLog } from '~codeyam/utils';
 import gatherDataForMocks from './gatherDataForMocks';
 import enrichArrayTypesFromChildSignatures from './enrichArrayTypesFromChildSignatures';
 import enrichUnknownTypesFromSourceEquivalencies from './enrichUnknownTypesFromSourceEquivalencies';
+// import propagateArrayItemSchemas from './propagateArrayItemSchemas';
 export interface GenerateDataStructureArgs {
   entity: Entity;
   dependentAnalyses: ReadonlyAnalysisMap;
@@ -469,11 +470,34 @@ export default function generateDataStructure({
 
         if (existingSchema) {
           // Merge schemas - child schemas add to parent schemas
+          // But prefer more specific types (without | undefined) when both exist
+          const mergedSignatureSchema = { ...existingSchema.signatureSchema };
+          for (const path in childSchema.signatureSchema) {
+            const existingType = mergedSignatureSchema[path];
+            const childType = childSchema.signatureSchema[path];
+            if (!existingType) {
+              mergedSignatureSchema[path] = childType;
+            } else {
+              // Prefer the more specific (narrower) type
+              const existingIsOptional =
+                existingType.includes('| undefined') ||
+                existingType.includes('| null');
+              const childIsOptional =
+                childType.includes('| undefined') ||
+                childType.includes('| null');
+              if (childIsOptional && !existingIsOptional) {
+                // Keep existing - it's more specific
+              } else if (!childIsOptional && existingIsOptional) {
+                // Use child - it's more specific
+                mergedSignatureSchema[path] = childType;
+              } else {
+                // Same specificity - use child (original behavior)
+                mergedSignatureSchema[path] = childType;
+              }
+            }
+          }
           mergedDataStructure.dependencySchemas[schemaFilePath][schemaName] = {
-            signatureSchema: {
-              ...existingSchema.signatureSchema,
-              ...childSchema.signatureSchema,
-            },
+            signatureSchema: mergedSignatureSchema,
             returnValueSchema: mergeJsonTypeDefinitions(
               existingSchema.returnValueSchema as Record<string, unknown>,
               childSchema.returnValueSchema as Record<string, unknown>,
@@ -560,6 +584,13 @@ export default function generateDataStructure({
       allImportedExports,
     );
 
+    // DISABLED: Testing if ternary fix eliminates the need for this heuristic
+    // Propagate array item schemas between arrays that likely have the same type.
+    // When one array (e.g., entities) has item schema traced but another similar array
+    // (e.g., currentEntities) doesn't (because it's only used in an OR expression fallback),
+    // copy the item schema from the rich array to the empty one.
+    // propagateArrayItemSchemas(mergedDataStructure.dependencySchemas);
+
     let dataForMocks = gatherDataForMocks(
       allImportedExports,
       mergedDataStructure.dependencySchemas,