@codeyam/codeyam-cli 0.1.0-staging.b8a55ba → 0.1.0-staging.c90f8c9

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

@@ -119,6 +119,17 @@ const stringMethodsSet = new Set([
 ]);
 export const allMethodsSet = new Set([...arrayMethodsSet, ...stringMethodsSet]);
 
+// Methods that exist in both stringMethodsSet and arrayMethodsSet.
+// When ONLY these methods are called on an object, we can't determine if it's a string or array.
+// Don't infer 'string' type from these alone - leave as 'unknown' for other type resolution.
+const stringArrayAmbiguousMethodsSet = new Set([
+  'includes', // exists in both String.includes() and Array.includes()
+  'indexOf', // exists in both String.indexOf() and Array.indexOf()
+  'lastIndexOf', // exists in both String.lastIndexOf() and Array.lastIndexOf()
+  'concat', // exists in both String.concat() and Array.concat()
+  'slice', // exists in both String.slice() and Array.slice()
+]);
+
 const signatureKeyWord = 'signature';
 const returnValueKeyWord = 'functionCallReturnValue';
 
@@ -128,12 +139,14 @@ const signatureRegExp = new RegExp(`^${signatureKeyWord}\\[\\d+\\]$`);
 
 // --- Caching splitOutsideParentheses ---
 // Instead of splitting the same string repeatedly, we cache the result.
+// IMPORTANT: Do NOT strip ::cyDuplicateKey:: markers - they are critical for
+// distinguishing variable reassignments (e.g., fetcher vs fetcher::cyDuplicateKey1::).
+// Stripping them causes schema contamination where fields from one type-parameterized
+// call get incorrectly attributed to another.
 const splitCache = new Map<string, string[]>();
 function cachedSplit(str: string): string[] {
   if (splitCache.has(str)) return splitCache.get(str)!;
-  const parts = splitOutsideParentheses(str).map((p) =>
-    p.replace(/::cyDuplicateKey\d+::/g, ''),
-  );
+  const parts = splitOutsideParentheses(str);
   splitCache.set(str, parts);
   return parts;
 }
@@ -695,7 +708,14 @@ function handleFunctionMapping(
         allProperties.every((prop) => stringMethodsSet.has(getMethodName(prop)))
       ) {
         if (allProperties.every((prop) => isValidStringMethod(prop))) {
-          keyMapping[previousPath] = 'string';
+          // Don't infer string if ALL methods are ambiguous between string and array
+          // (like includes, indexOf, concat, slice - these exist on both types)
+          const hasOnlyStringArrayAmbiguousMethods = allProperties.every(
+            (prop) => stringArrayAmbiguousMethodsSet.has(getMethodName(prop)),
+          );
+          if (!hasOnlyStringArrayAmbiguousMethods) {
+            keyMapping[previousPath] = 'string';
+          }
         } else {
           return false;
         }
@@ -716,19 +736,36 @@ function handleFunctionMapping(
 
     // Don't add [] element for ambiguous methods without other array evidence
     // Also don't add [] if the path was already identified as a string type
+    // Also don't add [] if the method is ambiguous between string and array (like includes)
     const methodName = getMethodName(lastPart);
     const isAmbiguousMethod = ambiguousArrayMethodsSet.has(methodName);
+    const isStringArrayAmbiguous =
+      stringArrayAmbiguousMethodsSet.has(methodName);
     const isStringType = keyMapping[previousPath] === 'string';
     if (
       !isValidFunctionCall(previousPart) &&
       arrayMethodsSet.has(methodName) &&
       !keyMapping[previousPath + '[]'] &&
       !isAmbiguousMethod &&
+      !isStringArrayAmbiguous &&
       !isStringType
     ) {
       keyMapping[previousPath + '[]'] = 'unknown';
     }
 
+    // For primitive-returning methods (like includes, indexOf, some, every),
+    // also delete the .functionCallReturnValue children since the return value
+    // is just a primitive (boolean/number) and not useful data.
+    // For other methods (like filter, map), keep children for transformation.
+    const isPrimitiveReturning = primitiveReturningMethodsSet.has(methodName);
+    if (isPrimitiveReturning) {
+      for (const otherPath of Object.keys(keyMapping)) {
+        if (otherPath.startsWith(path + '.')) {
+          delete keyMapping[otherPath];
+        }
+      }
+    }
+
     delete keyMapping[path];
     return true;
   }
@@ -954,14 +991,34 @@ function clearAttributes(
     }
   }
 
+  // Track paths that have primitive-returning method calls (like includes, some, every)
+  // These need cleanup even if we can't determine the base type
+  const pathsWithPrimitiveReturningMethods = new Set<string>();
+
   for (const key in functionCallsOnObjects) {
     const functionCalls = functionCallsOnObjects[key];
+
+    // Check if any method calls are primitive-returning
+    const hasPrimitiveReturningMethods = functionCalls.some((f) =>
+      primitiveReturningMethodsSet.has(getMethodName(f)),
+    );
+    if (hasPrimitiveReturningMethods) {
+      pathsWithPrimitiveReturningMethods.add(key);
+    }
+
     if (
       functionCalls.every(
         (f) => stringMethodsSet.has(getMethodName(f)) && isValidStringMethod(f),
       )
     ) {
-      mapping[key] = 'string';
+      // Don't infer string if ALL methods are ambiguous between string and array
+      // (like includes, indexOf, concat, slice - these exist on both types)
+      const hasOnlyStringArrayAmbiguousMethods = functionCalls.every((f) =>
+        stringArrayAmbiguousMethodsSet.has(getMethodName(f)),
+      );
+      if (!hasOnlyStringArrayAmbiguousMethods) {
+        mapping[key] = 'string';
+      }
     } else if (
       functionCalls.every(
         (f) => arrayMethodsSet.has(getMethodName(f)) && isValidArrayMethod(f),
@@ -983,10 +1040,28 @@ function clearAttributes(
   for (const key in mapping) {
     const value = mapping[key];
     if (knownTypes.has(value)) {
+      // Don't add string-typed array element paths (ending with []) to knownBasePaths.
+      // When an array element is typed as 'string' but has child paths (like data[].id),
+      // it's actually an object - the 'string' type is incorrect. The child paths
+      // describe the array element structure and should not be deleted.
+      //
+      // However, array-typed [] paths (like matrix[] where matrix is array of arrays)
+      // should still be in knownBasePaths so their method calls (filter, map, etc.)
+      // get cleaned up properly.
+      if (key.endsWith('[]') && value === 'string') {
+        continue;
+      }
       knownBasePaths.add(key);
     }
   }
 
+  // Also add paths with primitive-returning method calls (like includes, some, every)
+  // to knownBasePaths so their method call paths get cleaned up, even if we couldn't
+  // determine the base type (e.g., when only ambiguous methods like includes are used)
+  for (const path of pathsWithPrimitiveReturningMethods) {
+    knownBasePaths.add(path);
+  }
+
   for (const key in mapping) {
     const keyParts = cachedSplit(key);
     for (const basePath of knownBasePaths) {

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

@@ -0,0 +1,98 @@
+/**
+ * Converts null values to undefined (removes them) based on schema type constraints.
+ *
+ * When the LLM generates mock data, it uses `null` to represent "no value" because
+ * JSON doesn't support `undefined`. However, TypeScript types like `string | undefined`
+ * don't accept `null`.
+ *
+ * This function traverses data and schema together:
+ * - If schema type is "T | undefined" (but NOT "T | null"), convert null → undefined (delete key)
+ * - If schema type includes "null" (e.g., "T | null" or "T | null | undefined"), preserve null
+ * - If field not in schema, preserve as-is
+ *
+ * @param data The data object with potential null values
+ * @param schema The schema describing expected types
+ * @returns The data with null→undefined conversions applied (mutates original)
+ */
+export default function convertNullToUndefinedBySchema<T>(
+  data: T,
+  schema: unknown,
+): T {
+  // Handle null/undefined data
+  if (data === null || data === undefined) {
+    return data;
+  }
+
+  // Only process objects
+  if (typeof data !== 'object') {
+    return data;
+  }
+
+  // Handle arrays
+  if (Array.isArray(data)) {
+    // For arrays, the schema should be an array with one element describing the item type
+    const itemSchema = Array.isArray(schema) ? schema[0] : undefined;
+    for (let i = 0; i < data.length; i++) {
+      data[i] = convertNullToUndefinedBySchema(data[i], itemSchema);
+    }
+    return data;
+  }
+
+  // Handle objects
+  const dataObj = data as Record<string, unknown>;
+  const schemaObj = schema as Record<string, unknown> | undefined;
+
+  for (const key of Object.keys(dataObj)) {
+    const value = dataObj[key];
+    const fieldSchema = schemaObj?.[key];
+
+    if (value === null) {
+      // Check if schema allows null
+      if (shouldConvertNullToUndefined(fieldSchema)) {
+        // Delete the key (converts null to undefined)
+        delete dataObj[key];
+      }
+      // If schema allows null, preserve it
+    } else if (typeof value === 'object' && value !== null) {
+      // Recursively process nested objects/arrays
+      convertNullToUndefinedBySchema(value, fieldSchema);
+    }
+  }
+
+  return data;
+}
+
+/**
+ * Determines if a null value should be converted to undefined based on schema type.
+ *
+ * @param fieldSchema The schema type string or object for the field
+ * @returns true if null should be converted to undefined, false if null should be preserved
+ */
+function shouldConvertNullToUndefined(fieldSchema: unknown): boolean {
+  // If no schema for this field, preserve null (be conservative)
+  if (fieldSchema === undefined || fieldSchema === null) {
+    return false;
+  }
+
+  // If schema is a string type definition, check if it allows null
+  if (typeof fieldSchema === 'string') {
+    // Schema types that include "null" should preserve null values
+    // e.g., "string | null", "number | null | undefined", "null"
+    const allowsNull = fieldSchema.includes('null');
+    const allowsUndefined = fieldSchema.includes('undefined');
+
+    // If type allows undefined but NOT null, convert null to undefined
+    // e.g., "string | undefined" → convert null to undefined
+    // e.g., "string | null" → preserve null
+    // e.g., "string | null | undefined" → preserve null
+    if (allowsUndefined && !allowsNull) {
+      return true;
+    }
+
+    return false;
+  }
+
+  // If schema is an object or array, it's a nested structure
+  // Don't convert the container itself, just recurse into it
+  return false;
+}

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

@@ -307,7 +307,14 @@ export function fillInDirectSchemaGapsAndUnknowns({
           cleanOutBoundary(lastSubPathPart).match(/\[\d*\]/) &&
           !lastSubPathPart.match(/signature\[\d+\]/)
         ) {
-          if (schema[previousSubPath] !== 'array') {
+          // Fix 39: Don't overwrite explicit 'object' types with 'array'
+          // 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.
+          if (
+            schema[previousSubPath] !== 'array' &&
+            schema[previousSubPath] !== 'object'
+          ) {
             schema[previousSubPath] = 'array';
             changeMade = true;
           }

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

@@ -0,0 +1,129 @@
+import { awsLog } from '~codeyam/utils';
+
+/**
+ * Fixes null values for ID fields when the schema indicates they should be non-null numbers.
+ *
+ * The LLM sometimes generates `null` for ID fields (e.g., `"id": null`) when the schema
+ * type is `"number"` or `"number | undefined"` (but NOT `"number | null"`). This causes
+ * runtime issues when code checks `if (!data?.id)` expecting a truthy value.
+ *
+ * This function traverses data and schema together:
+ * - If field name looks like an ID field AND value is null AND schema doesn't allow null,
+ *   replace with a valid default value (1 for numbers, generated UUID for strings)
+ *
+ * @param data The data object with potential null ID values
+ * @param schema The schema describing expected types
+ * @param path Current path in the data structure (for logging)
+ * @returns The data with null IDs fixed (mutates original)
+ */
+export default function fixNullIdsBySchema<T>(
+  data: T,
+  schema: unknown,
+  path: string = '',
+): T {
+  // Handle null/undefined data
+  if (data === null || data === undefined) {
+    return data;
+  }
+
+  // Only process objects
+  if (typeof data !== 'object') {
+    return data;
+  }
+
+  // Handle arrays
+  if (Array.isArray(data)) {
+    // For arrays, the schema should be an array with one element describing the item type
+    const itemSchema = Array.isArray(schema) ? schema[0] : undefined;
+    for (let i = 0; i < data.length; i++) {
+      data[i] = fixNullIdsBySchema(data[i], itemSchema, `${path}[${i}]`);
+    }
+    return data;
+  }
+
+  // Handle objects
+  const dataObj = data as Record<string, unknown>;
+  const schemaObj = schema as Record<string, unknown> | undefined;
+
+  for (const key of Object.keys(dataObj)) {
+    const value = dataObj[key];
+    const fieldSchema = schemaObj?.[key];
+    const fieldPath = path ? `${path}.${key}` : key;
+
+    if (value === null && isIdField(key)) {
+      // Check if schema indicates this should be a non-null number
+      const replacement = getIdReplacementValue(fieldSchema);
+      if (replacement !== null) {
+        dataObj[key] = replacement;
+        awsLog(
+          `CodeYam: Fixed null ID field "${fieldPath}": null -> ${replacement}`,
+        );
+      }
+    } else if (typeof value === 'object' && value !== null) {
+      // Recursively process nested objects/arrays
+      fixNullIdsBySchema(value, fieldSchema, fieldPath);
+    }
+  }
+
+  return data;
+}
+
+/**
+ * Pattern for field names that are likely ID fields.
+ * Matches: id, Id, ID, userId, user_id, quoteId, quote_id, etc.
+ */
+const ID_FIELD_PATTERNS = [
+  /^id$/i, // Exact match for "id", "Id", "ID"
+  /Id$/, // Ends with "Id" (camelCase): userId, quoteId
+  /_id$/i, // Ends with "_id" (snake_case): user_id, quote_id
+  /^.*_id$/i, // Contains "_id": some_object_id
+];
+
+/**
+ * Determines if a field name looks like an ID field.
+ */
+function isIdField(fieldName: string): boolean {
+  return ID_FIELD_PATTERNS.some((pattern) => pattern.test(fieldName));
+}
+
+/**
+ * Gets the replacement value for a null ID based on schema type.
+ * Returns null if the schema allows null values (no replacement needed).
+ *
+ * @param fieldSchema The schema type for the field
+ * @returns Replacement value (1 for numbers, generated string for strings) or null if no replacement
+ */
+function getIdReplacementValue(fieldSchema: unknown): number | string | null {
+  // If no schema for this field, be conservative - don't replace
+  if (fieldSchema === undefined || fieldSchema === null) {
+    return null;
+  }
+
+  // If schema is a string type definition
+  if (typeof fieldSchema === 'string') {
+    // If schema explicitly allows null, don't replace
+    if (fieldSchema.includes('null')) {
+      return null;
+    }
+
+    // If schema is a number type, return 1 as default
+    if (
+      fieldSchema === 'number' ||
+      fieldSchema.startsWith('number') ||
+      fieldSchema.includes('number')
+    ) {
+      return 1;
+    }
+
+    // If schema is a string type, return a generated ID
+    if (
+      fieldSchema === 'string' ||
+      fieldSchema.startsWith('string') ||
+      fieldSchema.includes('string')
+    ) {
+      return 'id-1';
+    }
+  }
+
+  return null;
+}

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

@@ -0,0 +1,156 @@
+import type { ExecutionFlow, ScenariosDataStructure } from '~codeyam/types';
+
+// Type for a single required value from ExecutionFlow
+type RequiredValue = NonNullable<ExecutionFlow['requiredValues']>[number];
+
+const DEFAULT_MAX_KEYS_PER_CHUNK = 8;
+
+export interface ChunkOptions {
+  maxKeysPerChunk?: number;
+}
+
+/**
+ * Chunk a large data structure into smaller pieces for focused LLM processing.
+ *
+ * Large schemas overwhelm LLMs, causing them to make mistakes on some keys.
+ * By processing smaller chunks, each key gets more focused attention.
+ *
+ * @param dataForMocks - The full data structure schema
+ * @param options - Chunking options (maxKeysPerChunk defaults to 8)
+ * @returns Array of smaller data structure chunks
+ */
+export function chunkDataStructure(
+  dataForMocks: ScenariosDataStructure['dataForMocks'],
+  options: ChunkOptions = {},
+): Array<ScenariosDataStructure['dataForMocks']> {
+  if (!dataForMocks || typeof dataForMocks !== 'object') {
+    return [dataForMocks];
+  }
+
+  const { maxKeysPerChunk = DEFAULT_MAX_KEYS_PER_CHUNK } = options;
+  const keys = Object.keys(dataForMocks);
+
+  // Don't chunk if already small enough
+  if (keys.length <= maxKeysPerChunk) {
+    return [dataForMocks];
+  }
+
+  const chunks: Array<ScenariosDataStructure['dataForMocks']> = [];
+
+  for (let i = 0; i < keys.length; i += maxKeysPerChunk) {
+    const chunkKeys = keys.slice(i, i + maxKeysPerChunk);
+    const chunk: ScenariosDataStructure['dataForMocks'] = {};
+
+    for (const key of chunkKeys) {
+      (chunk as Record<string, unknown>)[key] = (
+        dataForMocks as Record<string, unknown>
+      )[key];
+    }
+
+    chunks.push(chunk);
+  }
+
+  return chunks;
+}
+
+/**
+ * Get the requiredValues that are relevant to a specific chunk.
+ *
+ * When processing a chunk, we should include any requiredValues from the covered
+ * flows that reference keys in that chunk. This helps the LLM understand what
+ * values are expected for those keys.
+ *
+ * @param chunk - A chunk of the data structure
+ * @param executionFlows - All execution flows for the entity
+ * @param coveredFlowIds - The flow IDs covered by the current scenario
+ * @returns Array of requiredValues that reference keys in this chunk
+ */
+export function getRequiredValuesForChunk(
+  chunk: ScenariosDataStructure['dataForMocks'],
+  executionFlows: ExecutionFlow[],
+  coveredFlowIds: string[],
+): RequiredValue[] {
+  if (!chunk || typeof chunk !== 'object') {
+    return [];
+  }
+
+  const chunkKeys = Object.keys(chunk);
+  const relevantValues: RequiredValue[] = [];
+
+  // Get the covered flows
+  const coveredFlows = executionFlows.filter((flow) =>
+    coveredFlowIds.includes(flow.id),
+  );
+
+  for (const flow of coveredFlows) {
+    if (!flow.requiredValues) continue;
+
+    for (const rv of flow.requiredValues) {
+      if (!rv.attributePath) continue;
+
+      // Check if this requiredValue references a key in this chunk
+      for (const chunkKey of chunkKeys) {
+        if (pathMatchesKey(rv.attributePath, chunkKey)) {
+          relevantValues.push(rv);
+          break; // Don't add the same rv multiple times
+        }
+      }
+    }
+  }
+
+  return relevantValues;
+}
+
+/**
+ * Check if an attributePath references a given dataForMocks key.
+ * (Same logic as in extractCriticalDataKeys)
+ */
+function pathMatchesKey(attributePath: string, dataKey: string): boolean {
+  const normalizedPath = attributePath.replace('.functionCallReturnValue', '');
+
+  if (normalizedPath.startsWith(dataKey)) {
+    const afterKey = normalizedPath.slice(dataKey.length);
+    if (
+      afterKey === '' ||
+      afterKey.startsWith('.') ||
+      afterKey.startsWith('[')
+    ) {
+      return true;
+    }
+  }
+
+  // Try matching without type parameters
+  const keyWithoutTypes = removeTypeParameters(dataKey);
+  const pathWithoutTypes = removeTypeParameters(normalizedPath);
+
+  if (pathWithoutTypes.startsWith(keyWithoutTypes)) {
+    const afterKey = pathWithoutTypes.slice(keyWithoutTypes.length);
+    if (
+      afterKey === '' ||
+      afterKey.startsWith('.') ||
+      afterKey.startsWith('[')
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Remove type parameters from a function call string.
+ */
+function removeTypeParameters(str: string): string {
+  let result = str;
+  let prevLength = 0;
+
+  while (result.length !== prevLength) {
+    prevLength = result.length;
+    result = result.replace(/<[^<>]*>/g, '');
+  }
+
+  return result;
+}
+
+// Re-export extractCriticalDataKeys for backwards compatibility
+export { extractCriticalDataKeys } from './extractCriticalDataKeys';

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

@@ -0,0 +1,30 @@
+export default function deepEqual(obj1: unknown, obj2: unknown): boolean {
+  // Handle primitive types and null/undefined
+  if (obj1 === obj2) return true;
+  if (obj1 == null || obj2 == null) return false;
+  if (typeof obj1 !== 'object' || typeof obj2 !== 'object') return false;
+
+  // Handle Date objects
+  if (obj1 instanceof Date && obj2 instanceof Date) {
+    return obj1.getTime() === obj2.getTime();
+  }
+
+  // Handle Array objects
+  if (Array.isArray(obj1) && Array.isArray(obj2)) {
+    if (obj1.length !== obj2.length) return false;
+    return obj1.every((item, index) => deepEqual(item, obj2[index]));
+  }
+
+  // Handle regular objects
+  const keys1 = Object.keys(obj1);
+  const keys2 = Object.keys(obj2);
+
+  if (keys1.length !== keys2.length) return false;
+
+  return keys1.every((key) => {
+    if (!Object.prototype.hasOwnProperty.call(obj2, key)) return false;
+    const obj1AsAny = obj1 as any;
+    const obj2AsAny = obj2 as any;
+    return deepEqual(obj1AsAny[key], obj2AsAny[key]);
+  });
+}