@codeyam/codeyam-cli 0.1.0-staging.323686 → 0.1.0-staging.415103

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

@@ -16,6 +16,8 @@ import { awsLog } from '~codeyam/utils';
 import gatherDataForMocks from './gatherDataForMocks';
 import enrichArrayTypesFromChildSignatures from './enrichArrayTypesFromChildSignatures';
 import enrichUnknownTypesFromSourceEquivalencies from './enrichUnknownTypesFromSourceEquivalencies';
+import { transformationTracer } from './TransformationTracer';
+// import propagateArrayItemSchemas from './propagateArrayItemSchemas';
 export interface GenerateDataStructureArgs {
   entity: Entity;
   dependentAnalyses: ReadonlyAnalysisMap;
@@ -162,6 +164,25 @@ export default function generateDataStructure({
         return acc;
       }, {} as ReadonlyAnalysisMap);
 
+    // Include same-file child components in nonMockedDependentAnalyses.
+    // Same-file components (e.g., AgentCard defined in the same file as AgentTranscriptsPage)
+    // are NOT in importedExports, so the reduce above never includes them.
+    // But they ARE in dependentAnalyses and their full signatureSchema (with all prop fields)
+    // needs to be merged into the parent's dependencySchemas for array enrichment to work.
+
+    const sameFileAnalyses = dependentAnalyses[entity.filePath];
+    if (sameFileAnalyses) {
+      for (const name in sameFileAnalyses) {
+        if (name === entity.name) continue;
+        if (nonMockedDependentAnalyses[entity.filePath]?.[name]) continue;
+        const childAnalysis = sameFileAnalyses[name];
+        if (childAnalysis?.entityType === 'visual') {
+          nonMockedDependentAnalyses[entity.filePath] ||= {};
+          nonMockedDependentAnalyses[entity.filePath][name] = childAnalysis;
+        }
+      }
+    }
+
     // For non-mocked child components (like visual components), include their mocked
     // dependencies in allImportedExports. This ensures that when a parent component
     // renders a child that uses the same hook with different destructure patterns,
@@ -440,6 +461,29 @@ export default function generateDataStructure({
 
     const { isolatedDataStructure } = entity.metadata;
 
+    if (!isolatedDataStructure) {
+      awsLog(
+        'CodeYam: Skipping data structure generation — isolatedDataStructure is undefined (scope analysis may have failed)',
+        {
+          entityName: entity.name,
+          filePath: entity.filePath,
+        },
+      );
+      return analysis;
+    }
+
+    // Transformation tracing: start entity and capture isolated data structure
+    transformationTracer.startEntity({
+      name: entity.name,
+      entityType: entity.entityType,
+      filePath: entity.filePath,
+    });
+    transformationTracer.snapshot(entity.name, 'isolated', {
+      signatureSchema: isolatedDataStructure.signatureSchema,
+      returnValueSchema: isolatedDataStructure.returnValueSchema,
+      dependencySchemas: isolatedDataStructure.dependencySchemas,
+    });
+
     const mergedDataStructure = mergeInDependentDataStructure({
       importedExports: allImportedExports,
       dependentAnalyses: nonMockedDependentAnalyses,
@@ -457,6 +501,13 @@ export default function generateDataStructure({
     mergedDataStructure.environmentVariables =
       isolatedDataStructure.environmentVariables || [];
 
+    // Transformation tracing: capture merged data structure
+    transformationTracer.snapshot(entity.name, 'merged', {
+      signatureSchema: mergedDataStructure.signatureSchema,
+      returnValueSchema: mergedDataStructure.returnValueSchema,
+      dependencySchemas: mergedDataStructure.dependencySchemas,
+    });
+
     // Merge collected child dependency schemas into mergedDataStructure.
     // This ensures that when gatherDataForMocks looks up schemas for child imports,
     // the child's schemas are available.
@@ -469,11 +520,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>,
@@ -487,6 +561,13 @@ export default function generateDataStructure({
       }
     }
 
+    // Transformation tracing: capture after child schemas merged
+    transformationTracer.snapshot(entity.name, 'childSchemasMerged', {
+      signatureSchema: mergedDataStructure.signatureSchema,
+      returnValueSchema: mergedDataStructure.returnValueSchema,
+      dependencySchemas: mergedDataStructure.dependencySchemas,
+    });
+
     // console.info(
     //   'CODEYAM DEBUG: end merge',
     //   JSON.stringify(
@@ -509,32 +590,183 @@ export default function generateDataStructure({
 
     // Deduplicate function schemas in the merged data structure
     // The merge process might introduce duplicates even if individual schemas were clean
+    // Trace deduplication of signatureSchema
+    const sigBefore = { ...mergedDataStructure.signatureSchema };
     mergedDataStructure.signatureSchema = deduplicateFunctionSchemas(
       mergedDataStructure.signatureSchema,
     );
+    transformationTracer.traceSchemaTransformResult(
+      entity.name,
+      'deduplicateFunctionSchemas',
+      sigBefore,
+      mergedDataStructure.signatureSchema,
+      { schemaType: 'signature' },
+    );
+
+    // Trace deduplication of returnValueSchema
+    const rvBefore = { ...mergedDataStructure.returnValueSchema };
     mergedDataStructure.returnValueSchema = deduplicateFunctionSchemas(
       mergedDataStructure.returnValueSchema,
     );
+    transformationTracer.traceSchemaTransformResult(
+      entity.name,
+      'deduplicateFunctionSchemas',
+      rvBefore,
+      mergedDataStructure.returnValueSchema,
+      { schemaType: 'returnValue' },
+    );
 
-    // Also deduplicate dependency schemas
+    // Also deduplicate dependency schemas and clear known attributes
     for (const filePath in mergedDataStructure.dependencySchemas) {
-      for (const entityName in mergedDataStructure.dependencySchemas[
+      for (const depEntityName in mergedDataStructure.dependencySchemas[
         filePath
       ]) {
         const depSchema =
-          mergedDataStructure.dependencySchemas[filePath][entityName];
+          mergedDataStructure.dependencySchemas[filePath][depEntityName];
+
+        // Trace deduplication of dependency signatureSchema
+        const depSigBefore = { ...depSchema.signatureSchema };
         depSchema.signatureSchema = deduplicateFunctionSchemas(
           depSchema.signatureSchema,
         );
+        transformationTracer.traceSchemaTransformResult(
+          entity.name,
+          'deduplicateFunctionSchemas',
+          depSigBefore,
+          depSchema.signatureSchema,
+          { filePath, dependencyName: depEntityName, schemaType: 'signature' },
+        );
+
+        // Trace deduplication of dependency returnValueSchema
+        const depRvBefore = { ...depSchema.returnValueSchema };
         depSchema.returnValueSchema = deduplicateFunctionSchemas(
           depSchema.returnValueSchema,
         );
+        transformationTracer.traceSchemaTransformResult(
+          entity.name,
+          'deduplicateFunctionSchemas',
+          depRvBefore,
+          depSchema.returnValueSchema,
+          {
+            filePath,
+            dependencyName: depEntityName,
+            schemaType: 'returnValue',
+          },
+        );
 
-        clearAttributesFromMapping(depSchema.signatureSchema);
-        clearAttributesFromMapping(depSchema.returnValueSchema);
+        // Infer function types from child component usage BEFORE fillInSchemaGapsAndUnknowns.
+        // When a hook returns a property with type 'unknown' that is passed to a child
+        // component which calls it as a function (e.g., isEntityPending(entity)),
+        // promote it to 'function'. Without this, name heuristics like isLikelyBoolean
+        // would mistype "isEntityPending" as boolean because of the "is" prefix.
+        //
+        // sourceEquivalencies are in isolatedDataStructure.dependencySchemas (not in
+        // mergedDataStructure.dependencySchemas — they're dropped during the merge).
+        // The child's signatureSchema (with function call evidence) IS in the merged schemas.
+        {
+          const isolatedDepSchemas =
+            entity.metadata.isolatedDataStructure?.dependencySchemas;
+          if (isolatedDepSchemas) {
+            for (const childFilePath in isolatedDepSchemas) {
+              const childIsolated = isolatedDepSchemas[childFilePath];
+              for (const childName in childIsolated) {
+                const sourceEq = childIsolated[childName]?.sourceEquivalencies;
+                if (!sourceEq) continue;
+
+                // Get the child's signatureSchema from the MERGED schemas (richer)
+                const mergedChildSchema =
+                  mergedDataStructure.dependencySchemas[childFilePath]?.[
+                    childName
+                  ];
+                const sigSchema = mergedChildSchema?.signatureSchema;
+                if (!sigSchema) continue;
+
+                for (const childPath in sourceEq) {
+                  for (const source of sourceEq[childPath]) {
+                    const fcrvSuffix = '.functionCallReturnValue.';
+                    const fcrvIndex = source.schemaPath.indexOf(fcrvSuffix);
+                    if (fcrvIndex === -1) continue;
+
+                    const propName = source.schemaPath.slice(
+                      fcrvIndex + fcrvSuffix.length,
+                    );
+
+                    // Find the corresponding child signature path
+                    const entityCallPrefix = childName + '().';
+                    const sigPathBase = childPath.startsWith(entityCallPrefix)
+                      ? childPath.slice(entityCallPrefix.length)
+                      : childPath;
+
+                    // Check if the child's signatureSchema has a function call version
+                    let isFunction = false;
+                    for (const sigKey in sigSchema) {
+                      if (
+                        sigKey.startsWith(sigPathBase + '(') &&
+                        sigSchema[sigKey] === 'function'
+                      ) {
+                        isFunction = true;
+                        break;
+                      }
+                    }
+
+                    if (isFunction) {
+                      for (const rvKey in depSchema.returnValueSchema) {
+                        if (
+                          rvKey.endsWith('.' + propName) &&
+                          depSchema.returnValueSchema[rvKey] === 'unknown'
+                        ) {
+                          depSchema.returnValueSchema[rvKey] = 'function';
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+
+        // Fill in type gaps BEFORE clearing attributes, so evidence like .includes()
+        // is used for type inference before being deleted
+
+        depSchema.signatureSchema = fillInDirectSchemaGapsAndUnknowns({
+          schema: depSchema.signatureSchema,
+        });
+
+        depSchema.returnValueSchema = fillInDirectSchemaGapsAndUnknowns({
+          schema: depSchema.returnValueSchema,
+        });
+
+        // Trace clearAttributesFromMapping on dependency schemas
+        transformationTracer.traceSchemaTransform(
+          entity.name,
+          'clearAttributesFromMapping',
+          depSchema.signatureSchema,
+          clearAttributesFromMapping,
+          { filePath, dependencyName: depEntityName, schemaType: 'signature' },
+        );
+
+        transformationTracer.traceSchemaTransform(
+          entity.name,
+          'clearAttributesFromMapping',
+          depSchema.returnValueSchema,
+          clearAttributesFromMapping,
+          {
+            filePath,
+            dependencyName: depEntityName,
+            schemaType: 'returnValue',
+          },
+        );
       }
     }
 
+    // Transformation tracing: capture after deduplication
+    transformationTracer.snapshot(entity.name, 'deduplicated', {
+      signatureSchema: mergedDataStructure.signatureSchema,
+      returnValueSchema: mergedDataStructure.returnValueSchema,
+      dependencySchemas: mergedDataStructure.dependencySchemas,
+    });
+
     analysis.metadata ||= {};
     analysis.metadata.mergedDataStructure = mergedDataStructure;
 
@@ -543,29 +775,70 @@ export default function generateDataStructure({
     // expects survey.updatedAt, the array element type includes updatedAt.
     // Uses usageEquivalencies to trace data flow and only enrich arrays with fields
     // from children that actually receive elements from that specific array.
-    enrichArrayTypesFromChildSignatures(
-      allImportedExports,
+    transformationTracer.traceDependencySchemaChanges(
+      entity.name,
+      'enrichArrayTypesFromChildSignatures',
       mergedDataStructure.dependencySchemas,
-      mergedDataStructure.usageEquivalencies,
+      () =>
+        enrichArrayTypesFromChildSignatures(
+          allImportedExports,
+          mergedDataStructure.dependencySchemas,
+          mergedDataStructure.usageEquivalencies,
+        ),
     );
 
+    // Transformation tracing: capture after array types enriched
+    transformationTracer.snapshot(entity.name, 'arrayTypesEnriched', {
+      signatureSchema: mergedDataStructure.signatureSchema,
+      returnValueSchema: mergedDataStructure.returnValueSchema,
+      dependencySchemas: mergedDataStructure.dependencySchemas,
+    });
+
     // Enrich mocked dependency unknown types using sourceEquivalencies
     // When a mocked dependency returns unknown, but that data flows to a child component
     // with a known type, propagate the type back to the mocked dependency.
     // This prevents fillInDirectSchemaGapsAndUnknowns from guessing incorrectly
     // (e.g., 'data' becoming 'number' because pluralize thinks it's plural)
-    enrichUnknownTypesFromSourceEquivalencies(
-      isolatedDataStructure.dependencySchemas || {},
+    transformationTracer.traceDependencySchemaChanges(
+      entity.name,
+      'enrichUnknownTypesFromSourceEquivalencies',
       mergedDataStructure.dependencySchemas,
-      allImportedExports,
+      () =>
+        enrichUnknownTypesFromSourceEquivalencies(
+          isolatedDataStructure.dependencySchemas || {},
+          mergedDataStructure.dependencySchemas,
+          allImportedExports,
+        ),
     );
 
+    // Transformation tracing: capture after unknown types enriched
+    transformationTracer.snapshot(entity.name, 'unknownTypesEnriched', {
+      signatureSchema: mergedDataStructure.signatureSchema,
+      returnValueSchema: mergedDataStructure.returnValueSchema,
+      dependencySchemas: mergedDataStructure.dependencySchemas,
+    });
+
+    // 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,
       { entityName: entity.name },
     );
 
+    // Transformation tracing: capture after dataForMocks gathered
+    transformationTracer.snapshot(entity.name, 'dataForMocksGathered', {
+      signatureSchema: mergedDataStructure.signatureSchema,
+      returnValueSchema: mergedDataStructure.returnValueSchema,
+      dependencySchemas: mergedDataStructure.dependencySchemas,
+      dataForMocks,
+    });
+
     // Merge dataForMocks from non-mocked child analyses to include transitive dependency data.
     // This handles cases where grandchild trpc calls aren't in allImportedExports because
     // the grandchild's analysis wasn't in dependentAnalyses.
@@ -587,11 +860,25 @@ export default function generateDataStructure({
       }
     }
 
-    const finalizedArgumentsSchema = fillInDirectSchemaGapsAndUnknowns({
-      schema: { ...mergedDataStructure.signatureSchema },
-    });
+    const finalizedArgumentsSchema = { ...mergedDataStructure.signatureSchema };
+
+    // Trace fillInDirectSchemaGapsAndUnknowns
+    transformationTracer.traceSchemaTransform(
+      entity.name,
+      'fillInDirectSchemaGapsAndUnknowns',
+      finalizedArgumentsSchema,
+      (schema) => fillInDirectSchemaGapsAndUnknowns({ schema }),
+      { stage: 'finalization' },
+    );
 
-    clearAttributesFromMapping(finalizedArgumentsSchema);
+    // Trace clearAttributesFromMapping
+    transformationTracer.traceSchemaTransform(
+      entity.name,
+      'clearAttributesFromMapping',
+      finalizedArgumentsSchema,
+      clearAttributesFromMapping,
+      { stage: 'finalization' },
+    );
 
     const argumentsSchema = convertDotNotation(finalizedArgumentsSchema)
       .signature as JsonTypeDefinition[];
@@ -601,6 +888,12 @@ export default function generateDataStructure({
       dataForMocks,
     };
 
+    // Transformation tracing: capture final scenariosDataStructure
+    transformationTracer.snapshot(entity.name, 'finalized', {
+      signatureSchema: finalizedArgumentsSchema,
+      dataForMocks,
+    });
+
     return analysis;
   } catch (e) {
     awsLog('CodeYam Error: Error generating data structure', {

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

@@ -65,6 +65,10 @@ export default async function generateExecutionFlows({
   }
 
   if (!analysis.metadata.executionFlows) {
+    console.log(
+      `[GenerateExecutionFlows] Starting for ${entity.name} (${entity.filePath})`,
+    );
+
     // Build childEntityMetadata from dependentAnalyses for child flow merging
     // This maps child component names to their metadata (specifically isolatedDataStructure)
     const childEntityMetadata = buildChildEntityMetadata(
@@ -72,6 +76,16 @@ export default async function generateExecutionFlows({
       dependentAnalyses,
     );
 
+    const childCount = Object.keys(childEntityMetadata).length;
+    console.log(
+      `[GenerateExecutionFlows] Built childEntityMetadata with ${childCount} children`,
+    );
+    if (childCount > 0) {
+      console.log(
+        `[GenerateExecutionFlows] Will merge flows from children: [${Object.keys(childEntityMetadata).join(', ')}]`,
+      );
+    }
+
     const {
       result: { executionFlows, llmCall: executionFlowsLLMCall },
     } = await measureAndReportExecutionTime(
@@ -80,15 +94,24 @@ export default async function generateExecutionFlows({
           entity,
           mergedDataStructure: analysis.metadata.mergedDataStructure,
           model,
-          childEntityMetadata:
-            Object.keys(childEntityMetadata).length > 0
-              ? childEntityMetadata
-              : undefined,
+          childEntityMetadata: childCount > 0 ? childEntityMetadata : undefined,
         }),
       `Generating execution flows`,
       updateProgress,
     );
 
+    console.log(
+      `[GenerateExecutionFlows] Generated ${executionFlows.length} execution flows for ${entity.name}`,
+    );
+    for (const flow of executionFlows) {
+      const reqValues = flow.requiredValues
+        .map((rv) => `${rv.attributePath}=${rv.value}`)
+        .join(', ');
+      console.log(
+        `[GenerateExecutionFlows]   - Flow '${flow.id}': ${flow.name} [${reqValues}]`,
+      );
+    }
+
     analysis.metadata.executionFlows = executionFlows;
 
     if (executionFlowsLLMCall) {
@@ -114,7 +137,14 @@ export function buildChildEntityMetadata(
 ): Record<string, Entity['metadata']> {
   const childEntityMetadata: Record<string, Entity['metadata']> = {};
 
+  console.log(
+    `[BuildChildMetadata] Starting for entity: ${entity.name} (${entity.filePath})`,
+  );
+
   if (!dependentAnalyses) {
+    console.log(
+      `[BuildChildMetadata] No dependentAnalyses provided, returning empty`,
+    );
     return childEntityMetadata;
   }
 
@@ -122,18 +152,54 @@ export function buildChildEntityMetadata(
     entity.metadata?.isolatedDataStructure?.childBoundaryGatingConditions;
 
   if (!childBoundaryGatingConditions) {
+    console.log(
+      `[BuildChildMetadata] No childBoundaryGatingConditions found in isolatedDataStructure`,
+    );
+    console.log(
+      `[BuildChildMetadata] isolatedDataStructure keys: ${Object.keys(entity.metadata?.isolatedDataStructure ?? {}).join(', ') || 'none'}`,
+    );
     return childEntityMetadata;
   }
 
+  const childNames = Object.keys(childBoundaryGatingConditions);
+  console.log(
+    `[BuildChildMetadata] Found ${childNames.length} children in childBoundaryGatingConditions: [${childNames.join(', ')}]`,
+  );
+
+  // Log gating conditions for each child
+  for (const [childName, conditions] of Object.entries(
+    childBoundaryGatingConditions,
+  )) {
+    const isUnconditional = conditions.some(
+      (c) => c.location === 'unconditional',
+    );
+    console.log(
+      `[BuildChildMetadata] Child '${childName}': ${conditions.length} gating conditions, unconditional=${isUnconditional}`,
+    );
+    for (const condition of conditions) {
+      console.log(
+        `[BuildChildMetadata]   - path='${condition.path}' location='${condition.location}' isNegated=${condition.isNegated ?? false}`,
+      );
+    }
+  }
+
   const importedExports = entity.metadata?.importedExports ?? [];
+  console.log(
+    `[BuildChildMetadata] Entity has ${importedExports.length} importedExports`,
+  );
+
+  for (const childName of childNames) {
+    console.log(`[BuildChildMetadata] Looking up child '${childName}'...`);
 
-  for (const childName of Object.keys(childBoundaryGatingConditions)) {
     // Find the child in importedExports to get its file path
     const importedExport = importedExports.find(
       (ie) => ie.name === childName || ie.resolvedName === childName,
     );
 
     if (!importedExport) {
+      console.log(
+        `[BuildChildMetadata] Child '${childName}' NOT FOUND in importedExports`,
+      );
       continue;
     }
 
@@ -142,15 +208,57 @@ export function buildChildEntityMetadata(
       importedExport.resolvedFilePath ?? importedExport.filePath;
     const lookupName = importedExport.resolvedName ?? importedExport.name;
 
+    console.log(
+      `[BuildChildMetadata] Child '${childName}' found in importedExports: lookupPath='${lookupPath}' lookupName='${lookupName}'`,
+    );
+
     // Look up the child's analysis in dependentAnalyses
     const childAnalysis = dependentAnalyses[lookupPath]?.[lookupName];
 
-    if (childAnalysis?.entity?.metadata) {
-      // Cast to mutable type - the metadata is only read, not modified
-      childEntityMetadata[childName] = childAnalysis.entity
-        .metadata as Entity['metadata'];
+    if (!childAnalysis) {
+      console.log(
+        `[BuildChildMetadata] Child '${childName}' analysis NOT FOUND in dependentAnalyses[${lookupPath}][${lookupName}]`,
+      );
+      console.log(
+        `[BuildChildMetadata] Available paths in dependentAnalyses: [${Object.keys(dependentAnalyses).slice(0, 10).join(', ')}...]`,
+      );
+      continue;
+    }
+
+    if (!childAnalysis.entity?.metadata) {
+      console.log(
+        `[BuildChildMetadata] Child '${childName}' analysis found but entity.metadata is missing`,
+      );
+      continue;
+    }
+
+    // Log what we found in the child's metadata
+    const childIsolated = childAnalysis.entity.metadata.isolatedDataStructure;
+    const childConditionalUsages = childIsolated?.conditionalUsages ?? {};
+    const childConditionalCount = Object.keys(childConditionalUsages).length;
+
+    console.log(
+      `[BuildChildMetadata] Child '${childName}' FOUND with metadata:`,
+    );
+    console.log(
+      `[BuildChildMetadata]   - conditionalUsages: ${childConditionalCount} paths`,
+    );
+    if (childConditionalCount > 0) {
+      for (const [path, usages] of Object.entries(childConditionalUsages)) {
+        console.log(
+          `[BuildChildMetadata]     - '${path}': ${(usages as any[]).length} usages`,
+        );
+      }
     }
+
+    // Cast to mutable type - the metadata is only read, not modified
+    childEntityMetadata[childName] = childAnalysis.entity
+      .metadata as Entity['metadata'];
   }
 
+  console.log(
+    `[BuildChildMetadata] RESULT: Found metadata for ${Object.keys(childEntityMetadata).length} children: [${Object.keys(childEntityMetadata).join(', ')}]`,
+  );
+
   return childEntityMetadata;
 }