@codeyam/codeyam-cli 0.1.0-staging.596f0eb → 0.1.0-staging.6e699e5

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

@@ -38,6 +38,10 @@ export interface AnalysisOptions {
   forceAll?: boolean;
   updateProgress?: (detail: string) => void;
   modelString?: string;
+  /** Process data structure preparation sequentially instead of in parallel (for debugging) */
+  sequentialDataStructurePrep?: boolean;
+  /** Called after data structures are prepared, signaling orchestration can begin */
+  onAnalysisProducing?: () => void;
 }
 
 interface AnalyzeEntitiesArgs {
@@ -113,6 +117,14 @@ export default async function analyzeEntities({
     'Data structure preparation',
   );
 
+  // Signal that analysis can now produce captures
+  // This allows orchestration to start polling for ready analyses
+  awsLogDebugLevel(
+    1,
+    'Data structures prepared, analysis can now produce captures',
+  );
+  options.onAnalysisProducing?.();
+
   // Persist entities so isolatedDataStructure is available in future runs.
   // This ensures stable dependencyAnalyzedTreeSha across multiple analyzeEntities calls.
   const entitiesWithDataStructure = Array.from(allEntities).filter(
@@ -376,6 +388,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]);
         }

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

@@ -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/validateDependencyAnalyses.ts

@@ -1,5 +1,6 @@
 import type {
   Analysis,
+  Entity,
   ReadonlyAnalysisMap,
   ReadonlyAnalysis,
   ReadonlyEntity,
@@ -61,7 +62,10 @@ export default function validateDependencyAnalyses({
   for (const dependency of entity.metadata?.importedExports ?? []) {
     const dependencyFilePath =
       dependency.resolvedFilePath ?? dependency.filePath;
-    const dependencyName = dependency.resolvedName ?? dependency.name;
+    // Use the entity/import name, not the export name (resolvedName).
+    // For default exports, resolvedName is 'default' but the entity is stored
+    // under its actual identifier name (e.g., 'QuoteDetailsDrawer').
+    const dependencyName = dependency.name;
 
     // if the entity has duplicate dependencies, handle gracefully
     if (dependentAnalyses[dependencyFilePath]?.[dependencyName]) {
@@ -103,6 +107,23 @@ export default function validateDependencyAnalyses({
       continue;
     }
 
+    // Ensure the entity is attached to the analysis.
+    // The entity might not be attached if the analysis was loaded from the database
+    // without its entity being in the context's entity map.
+    // This is critical for generateDataStructure to merge child component tRPC calls.
+    let dependentEntity: ReadonlyEntity | undefined = dependentAnalysis.entity;
+    if (!dependentEntity) {
+      // Try to get the entity from the context
+      dependentEntity = context.getEntity(dependencyFilePath, dependencyName);
+      if (dependentEntity) {
+        // Attach the entity to the analysis (mutating, but necessary for downstream use)
+        // We need the double cast because ReadonlyEntity has readonly arrays that aren't
+        // assignable to Entity's mutable arrays.
+        (dependentAnalysis as unknown as Analysis).entity =
+          dependentEntity as unknown as Entity;
+      }
+    }
+
     // Store the dependent analysis
     dependentAnalyses[dependencyFilePath] ||= {};
     dependentAnalyses[dependencyFilePath][dependencyName] = dependentAnalysis;
@@ -125,12 +146,17 @@ export default function validateDependencyAnalyses({
       }
     }
 
-    validateDependencyAnalyses({
-      readonlyAnalysis: dependentAnalysis,
-      entity: dependentAnalysis.entity,
-      context: context,
-      dependentAnalyses,
-    });
+    // Only recurse if we have the entity. Without the entity, we can't process
+    // the dependency's own dependencies, but we can still use this dependency's
+    // analysis data (mergedDataStructure, etc.)
+    if (dependentEntity) {
+      validateDependencyAnalyses({
+        readonlyAnalysis: dependentAnalysis,
+        entity: dependentEntity,
+        context: context,
+        dependentAnalyses,
+      });
+    }
   }
 
   return { dependentAnalyses };

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

@@ -7,7 +7,7 @@ import type {
 import generateDataStructure from './scenarios/generateDataStructure';
 import generateChangesScenarioData from './scenarios/generateChangesScenarioData';
 import generateChangesScenarios from './scenarios/generateChangesScenarios';
-import generateKeyAttributes from './scenarios/generateKeyAttributes';
+import generateExecutionFlows from './scenarios/generateExecutionFlows';
 import { upsertAnalysesWithScenarios } from '~codeyam/database';
 import { Step } from './enums/steps';
 import recordStep from './recordStep';
@@ -22,6 +22,7 @@ import {
   pushAnalysisError,
   Semaphore,
 } from '~codeyam/utils';
+import deepEqual from '../utils/deepEqual';
 
 export interface AnalyzeChangeArgs {
   previousAnalysis: Analysis;
@@ -115,33 +116,48 @@ export default async function analyzeChange({
       }
     }
 
-    // KeyAttributes phase: I/O-bound LLM call, can run in parallel with other entities' Structure
-    if (!steps || steps.includes(Step.KeyAttributes)) {
-      awsLogDebugLevel(1, `Determining key attributes for ${entity.name}...`);
+    // ExecutionFlows phase: I/O-bound LLM call, can run in parallel with other entities' Structure
+    if (!steps || steps.includes(Step.ExecutionFlows)) {
+      awsLogDebugLevel(1, `Generating execution flows for ${entity.name}...`);
 
-      const { step: keyAttributesStep } = await recordStep(
-        'generateKeyAttributes',
+      const { step: executionFlowsStep } = await recordStep(
+        'generateExecutionFlows',
         () =>
-          generateKeyAttributes({
+          generateExecutionFlows({
             entity,
             analysis,
-            dependentAnalyses,
             model,
             updateProgress,
+            dependentAnalyses,
           }),
       );
-      analysis.status.steps.push(keyAttributesStep);
+      analysis.status.steps.push(executionFlowsStep);
     }
 
-    if (
-      analysis.metadata.scenariosDataStructure ===
-      previousAnalysis.metadata.scenariosDataStructure
-    ) {
+    const dataStructureUnchanged = deepEqual(
+      analysis.metadata.scenariosDataStructure,
+      previousAnalysis.metadata.scenariosDataStructure,
+    );
+
+    const executionFlowsUnchanged = deepEqual(
+      analysis.metadata.executionFlows,
+      previousAnalysis.metadata.executionFlows,
+    );
+
+    if (dataStructureUnchanged && executionFlowsUnchanged) {
       awsLogDebugLevel(
         1,
-        `Data structure unchanged, reusing previous scenarios for ${entity.name}...`,
+        `Data structure and execution flows 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

@@ -230,7 +230,7 @@ export default async function analyzeEntity({
 
       // For partial analyses, skip Step.Structure to reuse existing mergedDataStructure
       if (isPartialAnalysis && !steps) {
-        steps = [Step.KeyAttributes, Step.Scenarios, Step.Data];
+        steps = [Step.ExecutionFlows, Step.Scenarios, Step.Data];
         awsLog(
           'CodeYam: continuing from partial analysis, skipping Structure step',
           {
@@ -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 executionFlows (Structure + ExecutionFlows already ran)
+      const isCompleteDependencyAnalysis =
+        analyzeAsDependency && !!existingAnalysis.metadata?.executionFlows;
+
       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', {
@@ -375,7 +379,7 @@ export default async function analyzeEntity({
         }
 
         if (!steps || steps?.includes(Step.Scenarios)) {
-          delete existingAnalysis.metadata.keyAttributes;
+          delete existingAnalysis.metadata.executionFlows;
         }
 
         if (!steps || steps?.includes(Step.Data)) {

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

@@ -18,7 +18,7 @@ import {
   pushAnalysisError,
   Semaphore,
 } from '~codeyam/utils';
-import generateKeyAttributes from './scenarios/generateKeyAttributes';
+import generateExecutionFlows from './scenarios/generateExecutionFlows';
 
 export interface AnalyzeInitialArgs {
   analysis: Analysis;
@@ -83,30 +83,30 @@ export default async function analyzeInitial({
       }
     }
 
-    // Short-circuit for test mocking: only generate data structure, skip key attributes and scenarios
+    // Short-circuit for test mocking: only generate data structure, skip execution flows and scenarios
     if (process.env.ONLY_DATA_STRUCTURE === 'true') {
       awsLog(
-        'CodeYam: Skipping key attributes and scenario generation (ONLY_DATA_STRUCTURE=true)',
+        'CodeYam: Skipping execution flows and scenario generation (ONLY_DATA_STRUCTURE=true)',
       );
       return { analysis };
     }
 
-    // KeyAttributes phase: I/O-bound LLM call, can run in parallel with other entities' Structure
-    if (!steps || steps.includes(Step.KeyAttributes)) {
-      awsLogDebugLevel(1, `Determining key attributes for ${entity.name}...`);
+    // ExecutionFlows phase: I/O-bound LLM call, can run in parallel with other entities' Structure
+    if (!steps || steps.includes(Step.ExecutionFlows)) {
+      awsLogDebugLevel(1, `Generating execution flows for ${entity.name}...`);
 
-      const { step: dataStructureStep } = await recordStep(
-        'generateKeyAttributes',
+      const { step: executionFlowsStep } = await recordStep(
+        'generateExecutionFlows',
         () =>
-          generateKeyAttributes({
+          generateExecutionFlows({
             entity,
             analysis,
-            dependentAnalyses,
             model,
             updateProgress,
+            dependentAnalyses,
           }),
       );
-      analysis.status.steps.push(dataStructureStep);
+      analysis.status.steps.push(executionFlowsStep);
     }
 
     if (analyzeAsDependency) {
@@ -176,7 +176,6 @@ export default async function analyzeInitial({
       analysis.status.steps.push(mockDataStep);
     }
   } catch (error) {
-    console.log(error);
     pushAnalysisError({
       status: analysis.status,
       error,

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

@@ -12,5 +12,5 @@ export enum Step {
   // CodeQuality = 'codeQuality',
   Embed = 'embed',
   CodeExplanation = 'codeExplanation',
-  KeyAttributes = 'keyAttributes',
+  ExecutionFlows = 'executionFlows',
 }

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

@@ -0,0 +1,265 @@
+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.
+ *
+ * Uses usageEquivalencies to trace data flow and ONLY enrich arrays with fields
+ * from children that actually receive elements from that array.
+ *
+ * Example:
+ * - getSurveysAction returns { data: array }
+ * - usageEquivalencies shows: surveys[] -> SurveyCard().signature[0].survey
+ * - 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'],
+  usageEquivalencies?: DataStructure['usageEquivalencies'],
+): 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)) {
+      // Check if type is array (including nullable/optional variants like 'array | undefined')
+      if (!type.startsWith('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;
+
+  // Build a map from child component signature paths to their prop fields
+  // e.g., "SurveyCard().signature[0].survey" -> { "id": "string", "updatedAt": "date" }
+  const childSignatureFieldsByPath: Map<
+    string,
+    { propName: string; fields: Record<string, string> }
+  > = new Map();
+
+  // Helper to extract prop name and fields from a signature schema
+  const extractSignatureInfo = (
+    entityName: string,
+    schema: Record<string, string>,
+  ): void => {
+    // Group by prop name (e.g., signature[0].survey.id, signature[0].survey.name -> "survey")
+    const propGroups: Record<string, 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;
+        propGroups[propName] ||= {};
+        propGroups[propName][fieldPath] = type;
+      }
+    }
+
+    // Store 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 });
+      }
+    }
+  };
+
+  // Process all schemas in dependencySchemas
+  if (dependencySchemas) {
+    for (const [, entities] of Object.entries(dependencySchemas)) {
+      for (const [entityName, schemas] of Object.entries(entities)) {
+        const signatureSchema = schemas?.signatureSchema;
+        if (signatureSchema) {
+          extractSignatureInfo(entityName, signatureSchema);
+        }
+      }
+    }
+  }
+
+  if (childSignatureFieldsByPath.size === 0) return;
+
+  // Helper to check if a local variable name could be derived from a mocked function name
+  // e.g., "getSurveys" -> "surveys", "fetchUsers" -> "users", "loadData" -> "data"
+  // e.g., "getSurveysAction" -> "surveys" (removes "Action" suffix too)
+  const couldBeDerivedFrom = (
+    localVarName: string,
+    mockedFunctionName: string,
+  ): boolean => {
+    const normalizedVar = localVarName.toLowerCase().replace(/\[\]$/, '');
+    let normalizedFunc = mockedFunctionName.toLowerCase();
+
+    // Direct match (e.g., "surveys" from function "surveys")
+    if (normalizedFunc === normalizedVar) return true;
+
+    // Remove common prefixes like "get", "fetch", "load", "use"
+    const prefixPattern = /^(get|fetch|load|use)/i;
+    normalizedFunc = normalizedFunc.replace(prefixPattern, '');
+
+    // Remove common suffixes like "Action", "Query", "Mutation", "Handler"
+    const suffixPattern = /(action|query|mutation|handler)$/i;
+    normalizedFunc = normalizedFunc.replace(suffixPattern, '');
+
+    // Check if function name (without prefix/suffix) matches the variable name
+    if (normalizedFunc === normalizedVar) return true;
+
+    // Check for singular/plural relationship
+    // e.g., "survey" from "getSurveys" or "surveys" from "getSurvey"
+    if (
+      normalizedFunc.endsWith('s') &&
+      normalizedFunc.slice(0, -1) === normalizedVar
+    )
+      return true;
+    if (
+      normalizedVar.endsWith('s') &&
+      normalizedVar.slice(0, -1) === normalizedFunc
+    )
+      return true;
+
+    // Check if the array property name (like "data") is in the variable
+    // This handles cases like "const { data: surveys } = getSurveys()" where
+    // the local var might be the renamed destructured property
+    // Skip this for now as it's too loose
+
+    return false;
+  };
+
+  // For each mocked array, find which child signatures it flows to via usageEquivalencies
+  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;
+    }
+
+    // Find matching child signatures via usageEquivalencies
+    // Look for equivalencies where this array (or local variables derived from it)
+    // flows to a child component's signature
+    const matchedFields: Record<string, string> = {};
+
+    if (usageEquivalencies) {
+      // Check all equivalency entries for paths that could be derived from this array
+      for (const [sourcePath, targets] of Object.entries(usageEquivalencies)) {
+        // Check if this source path relates to our mocked array
+        // Direct match: "getSurveysAction().functionCallReturnValue.data[]"
+        // Indirect match: local variable like "surveys[]" that comes from the array
+        if (!sourcePath.endsWith('[]')) continue;
+
+        // Get the local variable name from the source path (e.g., "surveys[]" -> "surveys")
+        const localVarName = sourcePath.replace(/\[\]$/, '');
+
+        // Check if this local variable could have come from this mocked function
+        // Use heuristics: name matching (getSurveys -> surveys, getUsers -> users)
+        if (!couldBeDerivedFrom(localVarName, entityName)) {
+          continue;
+        }
+
+        for (const target of targets) {
+          // Target should be something like "SurveyCard().signature[0].survey"
+          // or "SurveyCard().signature[0].surveys[]"
+          const { schemaPath } = target;
+
+          // Look for signature fields that match this target
+          // Handle both singular (survey) and plural (surveys[]) forms
+          const normalizedTarget = schemaPath.replace(/\[\]$/, '');
+
+          for (const [signaturePath, info] of childSignatureFieldsByPath) {
+            if (normalizedTarget === signaturePath) {
+              // Found a match! Add all fields from this child signature
+              for (const [fieldPath, type] of Object.entries(info.fields)) {
+                if (!matchedFields[fieldPath]) {
+                  matchedFields[fieldPath] = type;
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+
+    // If no equivalencies matched, skip this array entirely
+    // This prevents the bug where ALL child signatures get merged into ALL arrays
+    if (Object.keys(matchedFields).length === 0) {
+      continue;
+    }
+
+    // Add array element type and matched fields
+    const elementPath = `${arrayPath}[]`;
+    schema[elementPath] = 'object';
+
+    for (const [fieldPath, type] of Object.entries(matchedFields)) {
+      const fullPath = `${elementPath}.${fieldPath}`;
+      if (!schema[fullPath]) {
+        schema[fullPath] = type;
+      }
+    }
+  }
+}

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

@@ -0,0 +1,102 @@
+import { DataStructure } from '~codeyam/types';
+
+/**
+ * Enriches mocked dependency return value types using sourceEquivalencies.
+ *
+ * When a mocked dependency returns a value with an `unknown` type, and that value
+ * is passed to a child component, we can infer the type from the child's signature.
+ * The sourceEquivalencies track this data flow.
+ *
+ * Example:
+ * - trpc.quote.getQuoteQuestionAnswers.useQuery().functionCallReturnValue.data is `unknown`
+ * - sourceEquivalencies shows this data flows to QuoteHeaderExcel().signature[0].questionAnswers
+ * - QuoteHeaderExcel's signatureSchema says signature[0].questionAnswers is `array | undefined`
+ * - Therefore, data should be `array | undefined`
+ *
+ * Without this enrichment, fillInDirectSchemaGapsAndUnknowns will guess the type
+ * based on the property name, often incorrectly (e.g., 'data' becomes 'number'
+ * because pluralize.isPlural('data') returns true).
+ */
+export default function enrichUnknownTypesFromSourceEquivalencies(
+  isolatedDependencySchemas: DataStructure['dependencySchemas'],
+  mergedDependencySchemas: DataStructure['dependencySchemas'],
+  mockedImports: { filePath?: string; name: string; isMocked?: boolean }[],
+): void {
+  // Build a map of mocked dependency schemas for quick lookup
+  const mockedSchemas = new Map<string, Record<string, string>>();
+  for (const imp of mockedImports) {
+    if (!imp.isMocked || !imp.filePath) continue;
+    const schema =
+      mergedDependencySchemas?.[imp.filePath]?.[imp.name]?.returnValueSchema;
+    if (schema) {
+      mockedSchemas.set(`${imp.filePath}:${imp.name}`, schema);
+    }
+  }
+
+  if (mockedSchemas.size === 0) return;
+
+  // Iterate over all sourceEquivalencies in all dependency schemas
+  for (const filePath in isolatedDependencySchemas) {
+    for (const entityName in isolatedDependencySchemas[filePath]) {
+      const depSchema = isolatedDependencySchemas[filePath][entityName];
+      const sourceEquivs = depSchema.sourceEquivalencies;
+      if (!sourceEquivs) continue;
+
+      // For each sourceEquivalency: key is destination, value contains sources
+      for (const [destinationPath, sources] of Object.entries(sourceEquivs)) {
+        // Parse the destination to get the child entity name and signature path
+        // e.g., "QuoteHeaderExcel().signature[0].questionAnswers" ->
+        //   entityName: "QuoteHeaderExcel", sigPath: "signature[0].questionAnswers"
+        const destMatch = destinationPath.match(/^(\w+)\(\)\.(.+)$/);
+        if (!destMatch) continue;
+
+        const [, destEntityName, destSigPath] = destMatch;
+
+        // Find the child's signatureSchema to get the destination type
+        let destType: string | undefined;
+        for (const depFilePath in mergedDependencySchemas) {
+          const childSchema =
+            mergedDependencySchemas[depFilePath][destEntityName];
+          if (childSchema?.signatureSchema?.[destSigPath]) {
+            destType = childSchema.signatureSchema[destSigPath];
+            break;
+          }
+        }
+
+        if (!destType || destType === 'unknown') continue;
+
+        // Now check each source to see if it's a mocked dependency with unknown type
+        for (const source of sources) {
+          const { scopeNodeName, schemaPath } = source;
+
+          // Find which mocked dependency this belongs to
+          for (const [key, schema] of mockedSchemas) {
+            const [mockedFilePath, mockedName] = key.split(':');
+
+            // Check if this source path is in the mocked dependency's schema
+            // The schemaPath contains the full path like:
+            // "trpc.quote.getQuoteQuestionAnswers.useQuery(...).functionCallReturnValue.data"
+            // We need to find it in the returnValueSchema
+            if (schema[schemaPath] === 'unknown') {
+              // Found an unknown type that flows to a known type!
+              schema[schemaPath] = destType;
+            }
+
+            // Also check without the functionCallReturnValue part
+            // (some schemas might have the transformed path)
+            const transformedPath = schemaPath.replace(
+              /\.functionCallReturnValue/g,
+              '',
+            );
+            if (
+              transformedPath !== schemaPath &&
+              schema[transformedPath] === 'unknown'
+            ) {
+              schema[transformedPath] = destType;
+            }
+          }
+        }
+      }
+    }
+  }
+}