@codeyam/codeyam-cli 0.1.0-staging.483fdc2 → 0.1.0-staging.62d4615

package/analyzer-template/packages/ai/src/lib/dataStructure/helpers/fillInSchemaGapsAndUnknowns.ts

@@ -152,8 +152,11 @@ export default function fillInSchemaGapsAndUnknowns(
           schema[previousSubPath],
         )
       ) {
-        const newValue =
-          checkIfKnownType(previousSubPath, functionKeysMapping) ?? 'object';
+        // When fillInUnknowns=false, add missing gaps as 'unknown' to preserve raw schema.
+        // When fillInUnknowns=true, infer the type using checkIfKnownType.
+        const newValue = fillInUnknowns
+          ? (checkIfKnownType(previousSubPath, functionKeysMapping) ?? 'object')
+          : 'unknown';
 
         if (
           !schema[previousSubPath] ||
@@ -166,10 +169,14 @@ export default function fillInSchemaGapsAndUnknowns(
 
       // Handle the wrong function chaining function().function()
       if (isFunction && !existingSchema(previousSubPath)) {
+        // When fillInUnknowns=false, use 'unknown' for non-function paths.
+        // When fillInUnknowns=true, infer the type.
         schema[previousSubPath] = previousSubPath.endsWith(')')
           ? 'function'
-          : (checkIfKnownType(previousSubPath, functionKeysMapping) ??
-            'object');
+          : fillInUnknowns
+            ? (checkIfKnownType(previousSubPath, functionKeysMapping) ??
+              'object')
+            : 'unknown';
         changeMade = true;
       }
 
@@ -458,7 +465,10 @@ export function fillInDirectSchemaGapsAndUnknowns({
         }
       } else if (schema[key] === 'unknown') {
         const newType = guessTypeForPath(key, 'string');
-        if (newType && schema[key] !== newType) {
+        // Don't convert 'unknown' to 'object' — 'object' is just inferred from
+        // having child properties, which isn't more useful than 'unknown' and
+        // prevents enrichment from filling in the actual type later.
+        if (newType && newType !== 'object' && schema[key] !== newType) {
           schema[key] = newType;
           changeMade = true;
         }
@@ -481,12 +491,44 @@ export function fillInDirectSchemaGapsAndUnknowns({
             // This handles spurious [] paths from components like JsonNode that handle
             // both arrays and objects. When metadata is explicitly typed as 'object',
             // paths like metadata[] (from dynamic iteration) should not change it.
+            const existingType = schema[previousSubPath];
+            const baseType = existingType?.split(' | ')[0];
+
+            // Also check if this path has meaningful object property children (non-[] children).
+            // If it does, it's an object with mixed access patterns (e.g., agent.entries
+            // AND agent[].type), not a pure array. Don't infer 'array' in that case.
+            // Exclude .length since it exists on arrays too and is NOT evidence of object-ness.
+            let hasObjectPropertyChildren = false;
+            if (baseType !== 'array' && baseType !== 'object') {
+              const dotPrefix = previousSubPath + '.';
+              const lengthPath = previousSubPath + '.length';
+              for (const schemaKey in schema) {
+                if (
+                  schemaKey.startsWith(dotPrefix) &&
+                  schemaKey !== lengthPath
+                ) {
+                  hasObjectPropertyChildren = true;
+                  break;
+                }
+              }
+            }
+
             if (
-              schema[previousSubPath] !== 'array' &&
-              schema[previousSubPath] !== 'object'
+              baseType !== 'array' &&
+              baseType !== 'object' &&
+              !hasObjectPropertyChildren
             ) {
-              schema[previousSubPath] = 'array';
-              changeMade = true;
+              // Preserve nullability from existing type (e.g., 'unknown | undefined' -> 'array | undefined')
+              let newType = 'array';
+              if (existingType?.includes(' | undefined')) {
+                newType = 'array | undefined';
+              } else if (existingType?.includes(' | null')) {
+                newType = 'array | null';
+              }
+              if (schema[previousSubPath] !== newType) {
+                schema[previousSubPath] = newType;
+                changeMade = true;
+              }
             }
           }
         }
@@ -502,14 +544,36 @@ export function fillInDirectSchemaGapsAndUnknowns({
             schema[previousSubPath],
           )
         ) {
-          const newValue = getKnownType(previousSubPath) ?? 'object';
-
+          const existingType = schema[previousSubPath];
+          const baseExistingType = existingType?.split(' | ')[0];
+          // Skip if the base type is already a structured type
           if (
-            !schema[previousSubPath] ||
-            schema[previousSubPath] !== newValue
+            !['object', 'array', 'function', 'async-function'].includes(
+              baseExistingType,
+            )
           ) {
-            schema[previousSubPath] = newValue;
-            changeMade = true;
+            let newValue = getKnownType(previousSubPath) ?? 'object';
+            // Don't overwrite 'unknown' with 'object' — 'object' is just
+            // inferred from child properties and isn't more useful than 'unknown'
+            if (
+              newValue === 'object' &&
+              existingType &&
+              existingType.split(' | ')[0] === 'unknown'
+            ) {
+              // preserve existing 'unknown' (possibly with nullability)
+            } else {
+              // Preserve nullability from existing type
+              if (existingType?.includes(' | undefined')) {
+                newValue = `${newValue} | undefined`;
+              } else if (existingType?.includes(' | null')) {
+                newValue = `${newValue} | null`;
+              }
+
+              if (!existingType || existingType !== newValue) {
+                schema[previousSubPath] = newValue;
+                changeMade = true;
+              }
+            }
           }
         }
 
@@ -778,10 +842,11 @@ function checkIfKnownType(
     return 'array';
   }
 
-  // When .includes() or .indexOf() is called with a variable argument AND we have .length,
-  // prefer array. This pattern (arr.length > 0 && arr.includes(item)) is common for arrays.
-  // But str.includes('literal') is common for strings - that case is handled by hasStringLiteralArgument.
-  if (isArray && hasLengthAccess && hasIncludesOrIndexOfWithVariable) {
+  // When .includes() or .indexOf() is called with a variable argument, prefer array.
+  // Pattern: arr.includes(item) -> likely array (checking if item exists in collection)
+  // String literals are already filtered by hasStringLiteralArgument, so if we get here
+  // with a variable argument, it's strong evidence of array membership testing.
+  if (isArray && hasIncludesOrIndexOfWithVariable) {
     return 'array';
   }
 

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

@@ -1,9 +1,12 @@
 import { Entity } from '~codeyam/types';
 import isolateScopes from './isolateScopes';
 import analyzeScope from './analyzeScope';
-import { FileAnalyzer } from '~codeyam/analyze';
+import { FileAnalyzer, transformationTracer } from '~codeyam/analyze';
 import { AI, SerializableDataStructure } from '~codeyam/ai';
-import { resetScopeDataStructureMetrics } from './dataStructure/ScopeDataStructure';
+import {
+  resetScopeDataStructureMetrics,
+  ScopeDataStructure,
+} from './dataStructure/ScopeDataStructure';
 
 // import { awsLog } from '~codeyam/utils';
 
@@ -91,8 +94,60 @@ export default async function generateEntityDataStructure({
   }
 
   // Inspect the runtime type of dataStructure to see if it must be serialized
+  // Note: When worker threads are used, dataStructure is already serialized (no toSerializable).
+  // Workers are disabled when CODEYAM_TRACE_TRANSFORMS=1 to enable full tracing.
   if ('toSerializable' in entityScope.dataStructure) {
-    return entityScope.dataStructure.toSerializable();
+    const scopeDataStructure =
+      entityScope.dataStructure as unknown as ScopeDataStructure;
+
+    // Trace the internal state BEFORE serialization - captures what methods return
+    if (transformationTracer.isEnabled()) {
+      transformationTracer.startEntity({
+        name: entity.name,
+        entityType: entity.entityType ?? 'unknown',
+        filePath: entity.filePath,
+      });
+
+      // Capture internal state - this is what getReturnValue/getFunctionSignature return
+      transformationTracer.snapshot(entity.name, 'scopeDataStructure', {
+        signatureSchema: scopeDataStructure.getFunctionSignature({
+          fillInUnknowns: true,
+        }),
+        returnValueSchema: scopeDataStructure.getReturnValue({
+          fillInUnknowns: true,
+        }),
+      });
+    }
+
+    const serialized = scopeDataStructure.toSerializable();
+
+    // Trace AFTER serialization - shows what gets output
+    if (transformationTracer.isEnabled()) {
+      // Build schema from external function calls for comparison
+      const externalSchemas: Record<string, string> = {};
+      for (const efc of serialized.externalFunctionCalls ?? []) {
+        for (const [path, type] of Object.entries(efc.schema ?? {})) {
+          externalSchemas[path] = type;
+        }
+      }
+
+      transformationTracer.snapshot(entity.name, 'serialized', {
+        signatureSchema:
+          serialized.functionResults?.[entity.name]?.signatureWithUnknowns,
+        returnValueSchema:
+          serialized.functionResults?.[entity.name]?.returnValueWithUnknowns,
+        // Include external function schemas to detect serialization gaps
+        dependencySchemas: {
+          externalFunctions: {
+            combined: {
+              returnValueSchema: externalSchemas,
+            },
+          },
+        },
+      });
+    }
+
+    return serialized;
   }
   return entityScope.dataStructure;
 }

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

@@ -18,6 +18,7 @@ import { AI, parseJsonSafe } from '~codeyam/ai';
 import convertNullToUndefinedBySchema from './dataStructure/helpers/convertNullToUndefinedBySchema';
 import convertTypeAnnotationsToValues from './dataStructure/helpers/convertTypeAnnotationsToValues';
 import fixNullIdsBySchema from './dataStructure/helpers/fixNullIdsBySchema';
+import coerceObjectsToPrimitivesBySchema from './dataStructure/helpers/coerceObjectsToPrimitivesBySchema';
 import { JsonTypeDefinition } from '~codeyam/types';
 import { deepMerge } from '~codeyam/generate';
 import {
@@ -1057,6 +1058,19 @@ export async function generateDataForScenario({
     );
   }
 
+  // Coerce objects/arrays to primitives when the schema expects a primitive type.
+  // The LLM sometimes generates an object where the schema expects "string",
+  // e.g., { body: { "env": "production" } } instead of { body: "some string" }.
+  // This causes runtime errors like "TypeError: body.match is not a function".
+  // Must run BEFORE convertCommaSeparatedStringsToArrays, which intentionally
+  // overrides schema types for array-like field names.
+  if (structure.dataForMocks && fullScenarioData.data.mockData) {
+    coerceObjectsToPrimitivesBySchema(
+      fullScenarioData.data.mockData,
+      structure.dataForMocks,
+    );
+  }
+
   // Convert comma-separated strings to arrays when appropriate.
   // The LLM sometimes generates strings like "color,size" instead of arrays
   // like ["color", "size"] when the schema type is incorrectly inferred as

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

@@ -743,6 +743,48 @@ function processScope({
   };
 }
 
+/**
+ * Check if a code string contains only type declarations (type aliases, interfaces, etc.)
+ * that don't contribute to runtime behavior. This is used to determine if the root scope
+ * should be considered "empty" for scope extraction purposes.
+ */
+function containsOnlyTypeDeclarations(code: string): boolean {
+  try {
+    const sourceFile = ts.createSourceFile(
+      'temp.ts',
+      code,
+      ts.ScriptTarget.Latest,
+      true,
+      ts.ScriptKind.TS,
+    );
+
+    // Check each statement - if any is NOT a type-only declaration, return false
+    for (const statement of sourceFile.statements) {
+      if (
+        ts.isTypeAliasDeclaration(statement) ||
+        ts.isInterfaceDeclaration(statement) ||
+        ts.isEnumDeclaration(statement) ||
+        // Import declarations that are type-only
+        (ts.isImportDeclaration(statement) &&
+          statement.importClause?.isTypeOnly) ||
+        // Export declarations that are type-only
+        (ts.isExportDeclaration(statement) && statement.isTypeOnly)
+      ) {
+        // This is a type-only declaration, continue checking
+        continue;
+      }
+      // Found a non-type statement
+      return false;
+    }
+
+    // All statements are type-only (or there are no statements)
+    return sourceFile.statements.length > 0;
+  } catch {
+    // If parsing fails, assume it's not type-only
+    return false;
+  }
+}
+
 /**
  * Main entry point.
  *
@@ -792,9 +834,15 @@ export default function isolateScopes(
   const jsxLimit = options?.jsxLimit ?? 10;
   processJSXForScope(isolatedScopes, generateSyntheticName, jsxLimit);
 
-  // If the root scope text is empty and there's only one child scope,
-  // return that child scope as the root scope
-  if (isolatedScopes.text.trim().length === 0) {
+  // If the root scope text is empty (or only contains type declarations) and there's
+  // only one child scope, return that child scope as the root scope.
+  // Type declarations (type aliases, interfaces) don't contribute to runtime behavior,
+  // so we treat them as "empty" for scope extraction purposes.
+  const rootTextIsEffectivelyEmpty =
+    isolatedScopes.text.trim().length === 0 ||
+    containsOnlyTypeDeclarations(isolatedScopes.text);
+
+  if (rootTextIsEffectivelyEmpty) {
     const childScopeArray = Object.values(isolatedScopes.childScopes);
     if (childScopeArray.length === 1) {
       return childScopeArray[0];

package/analyzer-template/packages/analyze/index.ts

@@ -41,6 +41,8 @@ export { default as mergeValidatedDataStructures } from './src/lib/files/scenari
 
 export { discoverDirectDependencies } from './src/lib/files/analyze/dependencyResolver';
 
+export { transformationTracer } from './src/lib/files/scenarios/TransformationTracer';
+
 export { default as getAnalysisError } from './src/lib/utils/getAnalysisError';
 export { default as measureAndReportExecutionTime } from './src/lib/utils/measureAndReportExecutionTime';
 

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

@@ -555,6 +555,42 @@ async function getEntityDataStructureAndFunctionCalls({
     },
   );
 
+  // Add same-file child components to dependencySchemas.
+  // Same-file components (e.g., AgentCard defined in the same file as AgentTranscriptsPage)
+  // appear in externalFunctionCalls and functionResults but NOT in importedExports or
+  // nodeModuleImports. Without this, their signatures are missing from dependencySchemas
+  // and enrichArrayTypesFromChildSignatures can't find child component field accesses.
+  const allDependencyNames = new Set(allDependencies.map((d) => d.name));
+
+  for (const efc of dataStructure.externalFunctionCalls) {
+    // Skip if already covered by importedExports or nodeModuleImports
+    if (allDependencyNames.has(efc.name)) continue;
+
+    const signatureSchema = getFunctionSignature(dataStructure, {
+      functionName: efc.name,
+    });
+
+    const returnValueSchema = getReturnValue(dataStructure, {
+      functionName: efc.name,
+    });
+
+    // Only add if we have signature or return value data
+    if (!signatureSchema && !returnValueSchema) continue;
+
+    const clonedSignatureSchema = { ...(signatureSchema ?? {}) };
+    const clonedReturnValueSchema = { ...(returnValueSchema ?? {}) };
+
+    const entityFilePath = entity.filePath;
+    dependencySchemas[entityFilePath] ||= {};
+    dependencySchemas[entityFilePath][efc.name] = {
+      signatureSchema: deduplicateFunctionSchemas(clonedSignatureSchema),
+      returnValueSchema: deduplicateFunctionSchemas(clonedReturnValueSchema),
+      usageEquivalencies: getUsageEquivalencies(dataStructure, efc.name) ?? {},
+      sourceEquivalencies:
+        getSourceEquivalencies(dataStructure, efc.name) ?? {},
+    };
+  }
+
   const rawReturnValue =
     getReturnValue(dataStructure, { fillInUnknowns: false }) ?? {};
 
@@ -870,9 +906,21 @@ export function determineMockedDependencies(entity: Entity) {
       // A schema with only "EntityName(): function" just indicates the entity is callable,
       // it doesn't mean there's actual return data to mock
       const hasReturnValue = hasActualReturnValueData(entityReturnValueSchema);
-      const complexReturnValue = Object.values(
-        entityReturnValueSchema ?? {},
-      ).some((value) => value === 'object' || value === 'array');
+      // Check for complex return types (object/array), accounting for nullable types
+      // e.g., 'object', 'object | null', 'array | undefined' should all count as complex.
+      // Also detect when functionCallReturnValue has nested child properties — this
+      // proves it's a structured type even if its declared type is still 'unknown'.
+      const returnValueKeys = Object.keys(entityReturnValueSchema ?? {});
+      const complexReturnValue =
+        Object.values(entityReturnValueSchema ?? {}).some((value) => {
+          const baseType = value?.split(' | ')[0];
+          return baseType === 'object' || baseType === 'array';
+        }) ||
+        returnValueKeys.some(
+          (key) =>
+            key.includes('functionCallReturnValue.') ||
+            key.includes('functionCallReturnValue['),
+        );
 
       // Check if this is a validation function that should always be mocked
       const isValidationFn = isValidationFunction(entityName);

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

@@ -5,6 +5,7 @@ import {
   measureAndReportExecutionTime,
   ProjectAnalyzer,
 } from '~codeyam/analyze';
+import { transformationTracer } from '../scenarios/TransformationTracer';
 import { getFileByPathSafe } from '../../utils/getFileByPath';
 import trackEntityCircularDependencies from './trackEntityCircularDependencies';
 import validateDependencyAnalyses from './validateDependencyAnalyses';
@@ -307,6 +308,10 @@ export default async function analyzeEntities({
   awsLog(
     `CodeYam: analyzeEntities: Analysis completed with ${analyses.length} analyses`,
   );
+
+  // Flush transformation trace if tracing is enabled
+  transformationTracer.flush();
+
   return analyses;
 
   // PHASE 3: Pure graph traversal