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

package/analyzer-template/packages/ai/src/lib/gatherRelevantDependentKeyAttributes.ts

@@ -1,4 +1,9 @@
-import { Entity, ReadonlyAnalysis, ReadonlyAnalysisMap } from '~codeyam/types';
+import {
+  DataStructure,
+  Entity,
+  ReadonlyAnalysis,
+  ReadonlyAnalysisMap,
+} from '~codeyam/types';
 import {
   joinParenthesesAndArrays,
   splitOutsideParenthesesAndArrays,
@@ -7,8 +12,13 @@ import { gatherAttributesMap } from './promptGenerators/gatherAttributesMap';
 
 export default function gatherRelevantDependentKeyAttributes(
   entity: Pick<Entity, 'name' | 'metadata'>,
+  mergedDataStructure: Omit<DataStructure, 'equivalentSignatureVariables'>,
   dependentAnalyses: ReadonlyAnalysisMap,
+  debug = false,
 ) {
+  const log = (...args: any[]) => {
+    if (debug) console.log('[gatherRelevantDependentKeyAttributes]', ...args);
+  };
   // console.info(
   //   'CODEYAM DEBUG: gatherRelevantDependentKeyAttributes inputs',
   //   entity.name,
@@ -52,10 +62,16 @@ export default function gatherRelevantDependentKeyAttributes(
   //   ),
   // );
 
-  const { associationMap } = gatherAttributesMap(entity);
+  const isolatedDataStructure = entity.metadata?.isolatedDataStructure;
+  const equivalentSignatureVariables =
+    isolatedDataStructure?.equivalentSignatureVariables ?? {};
+  const { associationMap } = gatherAttributesMap(
+    isolatedDataStructure ?? mergedDataStructure,
+    mergedDataStructure,
+    equivalentSignatureVariables,
+  );
 
-  const dependencySchemas =
-    entity.metadata?.isolatedDataStructure?.dependencySchemas;
+  const dependencySchemas = mergedDataStructure?.dependencySchemas;
   const relevantDependentKeyAttributes: ReadonlyAnalysis['metadata']['keyAttributes'][0][] =
     [];
   Object.keys(dependentAnalyses).forEach((path) => {
@@ -66,41 +82,213 @@ export default function gatherRelevantDependentKeyAttributes(
       if (!dependentKeyAtttributes || dependentKeyAtttributes.length === 0)
         return;
 
-      const dependencySchema = dependencySchemas?.[path]?.[entityName];
-      const signatureSchema = dependencySchema?.signatureSchema;
-      if (!signatureSchema) return;
+      log(`Processing dependent entity: ${entityName} from ${path}`);
+      log(`  Key attributes count: ${dependentKeyAtttributes.length}`);
+      log(
+        `  Key attribute paths: ${dependentKeyAtttributes.map((ka: any) => ka.internalPath).join(', ')}`,
+      );
+
+      // Get sourceEquivalencies from the dependent analysis's mergedDataStructure,
+      // not from dependencySchemas (which doesn't store them)
+      const sourceEquivalencies =
+        dependentAnalysis?.metadata?.mergedDataStructure?.sourceEquivalencies ??
+        {};
 
-      const sourceEquivalencies = dependencySchema?.sourceEquivalencies ?? {};
+      log(
+        `  sourceEquivalencies keys: ${Object.keys(sourceEquivalencies).join(', ')}`,
+      );
 
-      // If sourceEquivalencies is empty but the child has mocked imports,
-      // propagate key attributes directly since they affect the parent's visual output
+      // FIRST: Check for mocked imports and process those key attributes.
+      // Mocked-source key attributes are ALWAYS controllable (we control the mock data)
+      // regardless of whether the parent passes data to the child via props.
+      // This must happen BEFORE the signatureSchema check.
       if (Object.keys(sourceEquivalencies).length === 0) {
-        // Check both importedExports and nodeModuleImports for mocked imports
+        // Collect names of mocked imports
         const importedExports =
           dependentAnalysis.entity?.metadata?.importedExports ?? [];
         const nodeModuleImports =
           dependentAnalysis.entity?.metadata?.nodeModuleImports ?? {};
 
-        const hasMockedImportedExports = importedExports.some(
-          (imp: { isMocked?: boolean }) => imp.isMocked,
-        );
-        const hasMockedNodeModuleImports = Object.values(
-          nodeModuleImports,
-        ).some((imports: any[]) =>
-          imports?.some((imp: { isMocked?: boolean }) => imp.isMocked),
-        );
+        const mockedImportNames = new Set<string>();
+
+        // Collect mocked names from importedExports
+        for (const imp of importedExports) {
+          if ((imp as { isMocked?: boolean }).isMocked) {
+            mockedImportNames.add((imp as { name: string }).name);
+          }
+        }
 
-        const childHasMockedImports =
-          hasMockedImportedExports || hasMockedNodeModuleImports;
+        // Collect mocked names from nodeModuleImports
+        for (const imports of Object.values(nodeModuleImports)) {
+          for (const imp of imports as any[]) {
+            if ((imp as { isMocked?: boolean }).isMocked) {
+              mockedImportNames.add((imp as { name: string }).name);
+            }
+          }
+        }
 
-        if (childHasMockedImports) {
+        if (mockedImportNames.size > 0) {
           for (const dependentKeyAttribute of dependentKeyAtttributes) {
-            relevantDependentKeyAttributes.push({
-              ...dependentKeyAttribute,
-              dependentEntityName: entityName,
-              originalEntityName: entityName,
-              filePath: path,
-            } as any);
+            // Include key attributes that come from controllable data sources:
+            // 1. Mocked data sources (like getScenarioDisplayState())
+            // 2. Arguments/props passed to the child (signature[N].*)
+            // Exclude attributes that are clearly just the prop name itself (like "size")
+            const externalPath = dependentKeyAttribute.externalPath || '';
+            const dataStructurePath =
+              dependentKeyAttribute.dataStructurePath || '';
+
+            const comesFromMockedSource = Array.from(mockedImportNames).some(
+              (mockedName) =>
+                externalPath.includes(`${mockedName}(`) ||
+                externalPath.includes(`${mockedName}.`) ||
+                dataStructurePath.includes(`${mockedName}(`) ||
+                dataStructurePath.includes(`${mockedName}.`) ||
+                dataStructurePath.startsWith(mockedName),
+            );
+
+            // Check if it comes from an argument (signature[N].something.deeper)
+            // but not just a simple prop like "size" or "isOutdated"
+            const comesFromArgument =
+              externalPath.startsWith('signature[') &&
+              // Must have nested path (at least one dot after the prop name)
+              // e.g., signature[0].scenario.metadata.* is OK
+              // but signature[0].size is not (it's just a simple prop)
+              (externalPath.match(/\./g) || []).length >= 2;
+
+            if (comesFromMockedSource || comesFromArgument) {
+              // Compute internalPath if not already present
+              // For signature paths, strip the signature[N]. prefix
+              let internalPath = dependentKeyAttribute.internalPath;
+              if (!internalPath && externalPath.startsWith('signature[')) {
+                internalPath = externalPath.replace(/^signature\[\d+\]\./, '');
+              }
+              // If still no internalPath, use dataStructurePath or externalPath as fallback
+              if (!internalPath) {
+                internalPath = dataStructurePath || externalPath;
+              }
+
+              relevantDependentKeyAttributes.push({
+                ...dependentKeyAttribute,
+                dependentEntityName: entityName,
+                originalEntityName: entityName,
+                filePath: path,
+                internalPath,
+                dataStructurePath: internalPath,
+              } as any);
+            }
+          }
+          return;
+        }
+      }
+
+      // SECOND: For signature-based key attributes, require that the parent has
+      // the child in its dependencySchemas. This ensures we only include key attributes
+      // that are controllable via props the parent passes to the child.
+      const dependencySchema = dependencySchemas?.[path]?.[entityName];
+      const signatureSchema = dependencySchema?.signatureSchema;
+      if (!signatureSchema) return;
+
+      // Build a fallback mapping from parent's usageEquivalencies
+      // This helps when the child's sourceEquivalencies don't have a mapping
+      // For example, if parent passes `entity` to child's `signature[0]`,
+      // usageEquivalencies might have: entity -> [{schemaPath: 'signature[0]', scopeNodeName: entityName}]
+      const usageEquivalencies = mergedDataStructure?.usageEquivalencies ?? {};
+      const signatureToParentPath: Record<string, string> = {};
+
+      for (const parentPath in usageEquivalencies) {
+        const usages = usageEquivalencies[parentPath];
+        for (const usage of usages) {
+          if (usage.scopeNodeName !== entityName) continue;
+
+          // Extract signature path from schemaPath
+          // Format can be:
+          // 1. "functionName(args).signature[N]" or "functionName(args).signature[N].property" (real data)
+          // 2. "signature[N]" or "signature[N].property" (simplified/test format)
+          let signaturePath: string;
+          const signatureIndex = usage.schemaPath.indexOf('.signature[');
+          if (signatureIndex !== -1) {
+            // Full format: extract "signature[N]" or "signature[N].property" after the dot
+            signaturePath = usage.schemaPath.slice(signatureIndex + 1);
+          } else if (usage.schemaPath.startsWith('signature[')) {
+            // Simplified format: already starts with signature[
+            signaturePath = usage.schemaPath;
+          } else {
+            continue;
+          }
+
+          // Map child's signature path to parent's path
+          // e.g., 'signature[0]' -> 'entity'
+          signatureToParentPath[signaturePath] = parentPath;
+        }
+      }
+
+      // Handle sourceEquivalencies empty case with no mocked imports
+      // Try usageEquivalencies fallback for direct argument usage
+      if (Object.keys(sourceEquivalencies).length === 0) {
+        // No mocked imports, try usageEquivalencies fallback for direct argument usage
+        if (Object.keys(signatureToParentPath).length > 0) {
+          for (const dependentKeyAttribute of dependentKeyAtttributes) {
+            if (!dependentKeyAttribute.externalPath?.startsWith('signature['))
+              continue;
+
+            const dependentKeyAttributeExternalPathParts =
+              splitOutsideParenthesesAndArrays(
+                dependentKeyAttribute.externalPath,
+              );
+
+            // Try to find a matching signature path
+            for (
+              let i = dependentKeyAttributeExternalPathParts.length;
+              i > 0;
+              i--
+            ) {
+              const subExternalPath = joinParenthesesAndArrays(
+                dependentKeyAttributeExternalPathParts.slice(0, i),
+              );
+
+              if (signatureToParentPath[subExternalPath]) {
+                const parentPath = signatureToParentPath[subExternalPath];
+
+                // parentPath is already in parent's schema format (e.g., "signature[0].entity" or just "entity")
+                // We need to handle both cases
+                const parentPathStartsWithSignature =
+                  parentPath.startsWith('signature[');
+                let externalPath = parentPathStartsWithSignature
+                  ? parentPath
+                  : `signature[0].${parentPath}`;
+
+                // internalPath is parentPath without the signature[N]. prefix
+                let internalPath: string | undefined =
+                  parentPathStartsWithSignature
+                    ? parentPath.replace(/^signature\[\d+\]\./, '')
+                    : parentPath;
+
+                if (i < dependentKeyAttributeExternalPathParts.length) {
+                  const remainingPath = joinParenthesesAndArrays(
+                    dependentKeyAttributeExternalPathParts.slice(i),
+                  );
+                  externalPath = `${externalPath}.${remainingPath}`;
+                  internalPath = `${internalPath}.${remainingPath}`;
+                }
+
+                // Look up in associationMap for proper internal path
+                if (associationMap[externalPath]) {
+                  internalPath = associationMap[externalPath];
+                }
+
+                relevantDependentKeyAttributes.push({
+                  ...dependentKeyAttribute,
+                  dependentEntityName: entityName,
+                  originalEntityName: entityName,
+                  filePath: path,
+                  internalPath,
+                  externalPath,
+                  dataStructurePath: internalPath,
+                } as any);
+
+                break;
+              }
+            }
           }
         }
         return;
@@ -110,7 +298,17 @@ export default function gatherRelevantDependentKeyAttributes(
         const dependentKeyAttributeExternalPathParts =
           splitOutsideParenthesesAndArrays(dependentKeyAttribute.externalPath);
 
+        log(
+          `  Processing key attribute: ${dependentKeyAttribute.internalPath}`,
+        );
+        log(`    externalPath: ${dependentKeyAttribute.externalPath}`);
+        log(
+          `    externalPathParts: ${JSON.stringify(dependentKeyAttributeExternalPathParts)}`,
+        );
+
         let matchFound = false;
+
+        // First, try to match using child's sourceEquivalencies
         for (
           let i = dependentKeyAttributeExternalPathParts.length;
           i > 0;
@@ -120,21 +318,123 @@ export default function gatherRelevantDependentKeyAttributes(
             dependentKeyAttributeExternalPathParts.slice(0, i),
           );
 
-          for (const sourceEquivalencyPath in dependencySchema?.sourceEquivalencies ??
-            {}) {
+          // Use the sourceEquivalencies from the child's analysis
+          for (const sourceEquivalencyPath in sourceEquivalencies) {
             const sourceEquivalencyPathParts = splitOutsideParenthesesAndArrays(
               sourceEquivalencyPath,
             );
 
+            // Check if this sourceEquivalency is for a callback (first part starts with '(')
+            // Callback sourceEquivalencies have format: "(param) => ...).signature[0]"
+            // These map callback parameters, NOT direct component props.
+            // We should NOT match direct prop paths like "signature[0].queueJobs[]"
+            // against callback parameter paths.
+            const isCallbackSourceEquivalency =
+              sourceEquivalencyPathParts[0]?.startsWith('(');
+
             const relevantSourceEquivalencyPath = joinParenthesesAndArrays(
               sourceEquivalencyPathParts.slice(1),
             );
 
             if (relevantSourceEquivalencyPath !== subExternalPath) continue;
 
+            // If this is a callback sourceEquivalency and we're matching against
+            // a simple signature path, skip it. The callback's "signature[0]" refers
+            // to the callback's parameter, not the component's props.
+            // We should only use callback sourceEquivalencies when the key attribute
+            // is actually about data that flows through that callback.
+            if (
+              isCallbackSourceEquivalency &&
+              subExternalPath.startsWith('signature[')
+            ) {
+              // The callback's signature[0] maps to specific paths in the parent
+              // (e.g., currentlyExecuting.entities[]). Only match if the remaining
+              // path of the key attribute is a valid continuation of data that
+              // flows through the callback.
+              //
+              // For example, if callback maps to currentlyExecuting.entities[],
+              // then key attribute signature[0].entityType would be valid (entity.entityType)
+              // but signature[0].queueJobs[] would NOT be valid (queueJobs is not entity)
+              const mappedPaths = sourceEquivalencies[sourceEquivalencyPath];
+              const remainingPath =
+                i < dependentKeyAttributeExternalPathParts.length
+                  ? dependentKeyAttributeExternalPathParts.slice(i)
+                  : [];
+
+              // If there's remaining path after the match, check if it makes sense
+              // for the callback's data flow. The mapped paths tell us where the
+              // callback parameter comes FROM - we should only include key attributes
+              // that are about properties OF that parameter, not unrelated props.
+              if (remainingPath.length > 0) {
+                // The remaining path should be a property of the callback's parameter.
+                // The mapped paths show where the parameter COMES FROM, ending with
+                // the array element (e.g., entities[]). Valid remaining paths would be
+                // properties of that element.
+                //
+                // For example:
+                // - Mapped paths: currentlyExecuting.entities[], queueJobs[].entities[]
+                // - These all end with entities[], so callback receives entity objects
+                // - Valid remaining: entityType, sha (properties of entity)
+                // - Invalid remaining: queueJobs[] (sibling prop, not entity property)
+                //
+                // Key insight: if the remaining path appears as a CONTAINER in any
+                // mapped path (before the final []), it's a sibling prop, not a
+                // property of the callback parameter.
+                const firstRemainingPart = remainingPath[0];
+                const firstRemainingWithoutBrackets =
+                  firstRemainingPart.replace(/\[\]$/, '');
+
+                // Check if this remaining path appears as a container in mapped paths
+                // e.g., "queueJobs" appears in "signature[0].queueJobs[].entities[]"
+                // This means queueJobs is a container that HOLDS entities, not a
+                // property OF an entity
+                const isContainerInMappedPaths = mappedPaths.some((mp) => {
+                  const mpPath = mp.schemaPath || '';
+                  // Check if the path contains this as a container segment
+                  // e.g., ".queueJobs[]." or ".queueJobs." in the middle of the path
+                  return (
+                    mpPath.includes(`.${firstRemainingWithoutBrackets}[].`) ||
+                    mpPath.includes(`.${firstRemainingWithoutBrackets}.`)
+                  );
+                });
+
+                if (isContainerInMappedPaths) {
+                  log(
+                    `    SKIP callback match: ${subExternalPath} -> ${sourceEquivalencyPath} (${firstRemainingPart} is a container in mapped paths, not a property of callback param)`,
+                  );
+                  continue;
+                }
+
+                // Also check: if the remaining path doesn't appear ANYWHERE in the
+                // mapped paths, it's likely a sibling prop that has nothing to do
+                // with the callback. For example, if mapped paths are all like
+                // "currentlyExecuting.entities[]" and the remaining is "currentRun",
+                // currentRun doesn't appear in any mapped path, so it's a sibling.
+                const remainingAppearsInMappedPaths = mappedPaths.some((mp) => {
+                  const mpPath = mp.schemaPath || '';
+                  // Check if remaining path or its base appears anywhere in mapped path
+                  return (
+                    mpPath.includes(`.${firstRemainingWithoutBrackets}`) ||
+                    mpPath.includes(`${firstRemainingWithoutBrackets}.`) ||
+                    mpPath.includes(`${firstRemainingWithoutBrackets}[`)
+                  );
+                });
+
+                if (!remainingAppearsInMappedPaths) {
+                  log(
+                    `    SKIP callback match: ${subExternalPath} -> ${sourceEquivalencyPath} (${firstRemainingPart} not found in any mapped path, likely a sibling prop)`,
+                  );
+                  continue;
+                }
+              }
+            }
+
+            log(
+              `    MATCH via sourceEquivalencies: ${subExternalPath} -> ${sourceEquivalencyPath}`,
+            );
+
             const sourcePath =
-              dependencySchema?.sourceEquivalencies[sourceEquivalencyPath][0]
-                ?.schemaPath;
+              sourceEquivalencies[sourceEquivalencyPath][0]?.schemaPath;
 
             if (!sourcePath) continue;
 
@@ -157,6 +457,16 @@ export default function gatherRelevantDependentKeyAttributes(
               }
             }
 
+            // Fallback: compute internalPath if not found in associationMap
+            // For signature paths, strip the signature[N]. prefix
+            if (!internalPath && externalPath.startsWith('signature[')) {
+              internalPath = externalPath.replace(/^signature\[\d+\]\./, '');
+            }
+            // If still no internalPath, use externalPath as fallback
+            if (!internalPath) {
+              internalPath = externalPath;
+            }
+
             const dependentEntityName =
               dependentKeyAttribute.dependentEntityName
                 ? `${dependentKeyAttribute.dependentEntityName} (through ${entityName})`
@@ -169,17 +479,106 @@ export default function gatherRelevantDependentKeyAttributes(
               filePath: path, // File path for restructuring into nested format
               internalPath,
               externalPath,
+              // Transform dataStructurePath to parent's path structure
+              dataStructurePath: internalPath,
             } as any);
 
+            log(
+              `    INCLUDED via sourceEquivalencies: ${dependentKeyAttribute.internalPath} -> ${internalPath}`,
+            );
             matchFound = true;
             break;
           }
 
           if (matchFound) break;
         }
+
+        // Fallback: if no sourceEquivalency match, try using parent's usageEquivalencies
+        // This handles direct argument usage like entity.entityType
+        if (
+          !matchFound &&
+          dependentKeyAttribute.externalPath?.startsWith('signature[')
+        ) {
+          // Try to find a matching signature path in the usageEquivalencies-derived map
+          for (
+            let i = dependentKeyAttributeExternalPathParts.length;
+            i > 0;
+            i--
+          ) {
+            const subExternalPath = joinParenthesesAndArrays(
+              dependentKeyAttributeExternalPathParts.slice(0, i),
+            );
+
+            if (signatureToParentPath[subExternalPath]) {
+              const parentPath = signatureToParentPath[subExternalPath];
+
+              // parentPath is already in parent's schema format (e.g., "signature[0].entity" or just "entity")
+              // We need to handle both cases
+              const parentPathStartsWithSignature =
+                parentPath.startsWith('signature[');
+              let externalPath = parentPathStartsWithSignature
+                ? parentPath
+                : `signature[0].${parentPath}`;
+
+              // internalPath is parentPath without the signature[N]. prefix
+              let internalPath: string | undefined =
+                parentPathStartsWithSignature
+                  ? parentPath.replace(/^signature\[\d+\]\./, '')
+                  : parentPath;
+
+              if (i < dependentKeyAttributeExternalPathParts.length) {
+                const remainingPath = joinParenthesesAndArrays(
+                  dependentKeyAttributeExternalPathParts.slice(i),
+                );
+                externalPath = `${externalPath}.${remainingPath}`;
+                internalPath = `${internalPath}.${remainingPath}`;
+              }
+
+              // Look up the full external path in associationMap for proper internal path
+              const fullExternalPath = externalPath;
+              if (associationMap[fullExternalPath]) {
+                internalPath = associationMap[fullExternalPath];
+              }
+
+              const dependentEntityName =
+                dependentKeyAttribute.dependentEntityName
+                  ? `${dependentKeyAttribute.dependentEntityName} (through ${entityName})`
+                  : entityName;
+
+              relevantDependentKeyAttributes.push({
+                ...dependentKeyAttribute,
+                dependentEntityName,
+                originalEntityName: entityName,
+                filePath: path,
+                internalPath,
+                externalPath,
+                dataStructurePath: internalPath,
+              } as any);
+
+              log(
+                `    INCLUDED via usageEquivalencies: ${dependentKeyAttribute.internalPath} -> ${internalPath}`,
+              );
+              matchFound = true;
+              break;
+            }
+          }
+        }
+
+        if (!matchFound) {
+          log(
+            `    NOT INCLUDED: ${dependentKeyAttribute.internalPath} - no match found`,
+          );
+        }
       }
     });
   });
 
+  log(
+    `Result: ${relevantDependentKeyAttributes.length} key attributes gathered`,
+  );
+  log(
+    `  Paths: ${relevantDependentKeyAttributes.map((ka: any) => ka.internalPath).join(', ')}`,
+  );
+
   return relevantDependentKeyAttributes;
 }