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

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

@@ -208,10 +208,12 @@ export default function fillInSchemaGapsAndUnknowns(
 export function fillInDirectSchemaGapsAndUnknowns({
   scopeName,
   schema,
+  mergedSchema,
   attempts = 0,
 }: {
   scopeName?: string;
   schema: Record<string, string>;
+  mergedSchema?: Record<string, string>;
   attempts?: number;
 }) {
   try {
@@ -245,7 +247,9 @@ export function fillInDirectSchemaGapsAndUnknowns({
     const guessTypeForPath = (path: string, defaultType = 'string') => {
       let knownType = checkIfKnownType(path, functionKeysMapping);
       if (!knownType) {
-        knownType = checkIfObjectOrFunction(path, schema);
+        // Use mergedSchema for type inference if available (has more complete nested paths)
+        // Fall back to schema if mergedSchema is not provided
+        knownType = checkIfObjectOrFunction(path, mergedSchema ?? schema);
       }
 
       if (knownType && schema[path] !== knownType) {
@@ -303,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;
           }
@@ -373,10 +384,39 @@ export function fillInDirectSchemaGapsAndUnknowns({
       fillInDirectSchemaGapsAndUnknowns({
         scopeName,
         schema,
+        mergedSchema,
         attempts: ++attempts,
       });
     }
 
+    // Remove .length paths when the parent is typed as 'array' or 'string' (or nullable variants).
+    // These are built-in properties that were used for type inference but shouldn't appear
+    // in the final schema (they create { length: N } objects instead of proper arrays).
+    // However, if the parent could be an 'object' or other type, keep .length as it may be
+    // a custom property.
+    for (const key of Object.keys(schema)) {
+      const parts = splitOutsideParenthesesAndArrays(key);
+      if (parts[parts.length - 1] === 'length') {
+        const parentPath = joinParenthesesAndArrays(parts.slice(0, -1));
+        const parentType = schema[parentPath];
+        if (parentType) {
+          // Split union types and filter out nullable parts
+          const typeParts = parentType.split(' | ').map((t) => t.trim());
+          const nonNullableTypes = typeParts.filter(
+            (t) => t !== 'undefined' && t !== 'null',
+          );
+          // Only remove if ALL non-nullable types are array or string
+          // This ensures we don't remove .length from potential custom objects
+          if (
+            nonNullableTypes.length > 0 &&
+            nonNullableTypes.every((t) => t === 'array' || t === 'string')
+          ) {
+            delete schema[key];
+          }
+        }
+      }
+    }
+
     return schema;
   } catch (error) {
     console.info(
@@ -454,6 +494,8 @@ function checkIfKnownType(
   let isString: boolean | undefined;
   let hasStrongArrayEvidence = false;
   let hasOnlyAmbiguousArrayMethods = true;
+  let hasLengthAccess = false;
+  let hasArrayStringAmbiguousMethod = false;
 
   for (const functionOrAttributeName of functionAndAttributesKeysMapping[key] ??
     []) {
@@ -467,11 +509,18 @@ function checkIfKnownType(
       knownMethodCalls(functionOrAttributeName).includes('string') ||
       functionOrAttributeName === 'length';
 
-    // Check if this is strong evidence of an array
-    if (
-      STRONG_ARRAY_METHODS.has(methodName) ||
-      functionOrAttributeName === 'length'
-    ) {
+    // Track .length access
+    if (functionOrAttributeName === 'length') {
+      hasLengthAccess = true;
+    }
+
+    // Track methods that exist on both arrays and strings (like includes, indexOf)
+    if (couldBeArray && couldBeString && functionOrAttributeName !== 'length') {
+      hasArrayStringAmbiguousMethod = true;
+    }
+
+    // Check if this is strong evidence of an array (unambiguous array methods)
+    if (STRONG_ARRAY_METHODS.has(methodName)) {
       hasStrongArrayEvidence = true;
     }
 
@@ -495,10 +544,24 @@ function checkIfKnownType(
     }
   }
 
+  // Strong array evidence (unambiguous methods like .map, .filter) -> definitely array
+  if (isArray && hasStrongArrayEvidence) {
+    return 'array';
+  }
+
+  // When we have BOTH .length AND an ambiguous method like .includes(),
+  // prefer array. This pattern (checking .length AND calling .includes)
+  // is very common with arrays (e.g., arr.length > 0 && arr.includes(x))
+  // but rare with strings (you'd typically just call str.includes(x))
+  if (isArray && hasLengthAccess && hasArrayStringAmbiguousMethod) {
+    return 'array';
+  }
+
   if (isString) return 'string';
+
   // Only infer array if we have strong evidence OR not only ambiguous methods
   // This prevents router.push() from being incorrectly inferred as an array
-  if (isArray && (hasStrongArrayEvidence || !hasOnlyAmbiguousArrayMethods)) {
+  if (isArray && !hasOnlyAmbiguousArrayMethods) {
     return 'array';
   }
 }

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/dataStructure/helpers/getFunctionCallRoot.ts

@@ -1,11 +1,41 @@
 import { splitOutsideParenthesesAndArrays } from '../../splitOutsideParentheses';
 
+/**
+ * Find the position of the first '(' that is NOT inside angle brackets.
+ * Returns -1 if not found.
+ */
+function findFirstParenOutsideTypeParams(signature: string): number {
+  let angleDepth = 0;
+
+  for (let i = 0; i < signature.length; i++) {
+    const char = signature[i];
+
+    if (char === '<') {
+      angleDepth++;
+    } else if (char === '>') {
+      angleDepth--;
+    } else if (char === '(' && angleDepth === 0) {
+      return i;
+    }
+  }
+
+  return -1;
+}
+
 export default function getFunctionCallRoot(functionCallSignature: string) {
   const functionCallSignatureParts = splitOutsideParenthesesAndArrays(
     functionCallSignature,
   );
 
-  return functionCallSignatureParts[0]
-    .replace(/(cyScope\d+)F/, '$1')
-    .split('(')[0];
+  const firstPart = functionCallSignatureParts[0];
+
+  // Find the first '(' that's not inside type parameters (angle brackets)
+  // This handles cases like "useFetcher<{ data: UserData | null }>()"
+  // which should return "useFetcher<{ data: UserData | null }>"
+  // (preserving type params for scope node matching)
+  const parenPos = findFirstParenOutsideTypeParams(firstPart);
+
+  const result = parenPos >= 0 ? firstPart.substring(0, parenPos) : firstPart;
+
+  return result.replace(/(cyScope\d+)F/, '$1');
 }

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]);
+  });
+}