@codeyam/codeyam-cli 0.1.0-staging.596f0eb → 0.1.0-staging.6e699e5

package/analyzer-template/packages/ai/src/lib/dataStructure/equivalencyManagers/frameworks/ReactFrameworkManager.ts

@@ -17,6 +17,12 @@ interface UseStateInfo {
 export class ReactFrameworkManager implements EquivalencyManager {
   private useStateInfos: UseStateInfo[] = [];
   private useCallbackEquivalents: Record<string, string> = {};
+  // Track variables used as ref props - they should be typed as 'null'
+  // Format: { scopeNodeName -> Set of variable paths }
+  private refVariables: Map<string, Set<string>> = new Map();
+  // Track ref variable source paths for updating external function call schemas in finalize
+  // Format: { functionCallName -> Set of source paths (e.g., 'useAutoAnimate().functionCallReturnValue[]') }
+  private refVariableSources: Map<string, Set<string>> = new Map();
 
   postProcess(scopeNode: ScopeNode, scopeDataStructure: ScopeDataStructure) {
     this.handleUseState(scopeNode, scopeDataStructure);
@@ -139,7 +145,27 @@ export class ReactFrameworkManager implements EquivalencyManager {
     'main',
   ]);
 
-  finalize(_scopeNode: ScopeNode, _scopeDataStructure: ScopeDataStructure) {}
+  finalize(scopeNode: ScopeNode, scopeDataStructure: ScopeDataStructure) {
+    // Set all tracked ref variables to 'null' type
+    // This ensures mock data generation uses null instead of placeholder strings
+    const refVarsForScope = this.refVariables.get(scopeNode.name);
+    if (refVarsForScope) {
+      for (const refVar of refVarsForScope) {
+        scopeNode.schema[refVar] = 'null';
+      }
+    }
+
+    // Update external function call schemas with ref source paths
+    // This runs AFTER schema building is complete, so the null values won't be overwritten
+    for (const efc of scopeDataStructure.externalFunctionCalls) {
+      const refSourcePaths = this.refVariableSources.get(efc.name);
+      if (refSourcePaths) {
+        for (const sourcePath of refSourcePaths) {
+          efc.schema[sourcePath] = 'null';
+        }
+      }
+    }
+  }
 
   private findUseStateInfo(useStateCall: string) {
     return this.useStateInfos.find(
@@ -213,10 +239,18 @@ export class ReactFrameworkManager implements EquivalencyManager {
             });
           }
 
+          // Get the initial value path (what signature[0] is equivalent to)
+          const initialValuePath = equivalentValues[0].schemaPath;
+          const initialValueScopeName = equivalentValues[0].scopeNodeName;
+
+          // Note: Callback scope tracing (for useState(() => { return prop; }))
+          // is handled in getEquivalentSignatureVariables() where the full
+          // equivalency database is available for deep tracing.
+
           scopeDataStructure.addEquivalency(
             relevantUseStateInfo.value,
-            equivalentValues[0].schemaPath,
-            scopeNode.name,
+            initialValuePath,
+            initialValueScopeName,
             scopeNode,
             'useState value equivalency',
           );
@@ -382,90 +416,126 @@ export class ReactFrameworkManager implements EquivalencyManager {
     let propagated = false;
     const functionCallSignature = getFunctionCallSignature(subPathParts);
 
-    const relevantUseStateInfo = this.findUseStateInfo(functionCallSignature);
+    let relevantUseStateInfo = this.findUseStateInfo(functionCallSignature);
+
+    // If we didn't find a useState call directly, check if the function being called
+    // is a setter variable (e.g., setWorkouts from useState)
+    if (!relevantUseStateInfo && functionCallSignature) {
+      // Extract the function name from the call (e.g., "setWorkouts" from "setWorkouts(data || [])")
+      const fnName = functionCallSignature.split('(')[0];
+      relevantUseStateInfo = this.useStateInfos.find(
+        (info) => info.setter === fnName,
+      );
+    }
 
     if (relevantUseStateInfo) {
       const pathParts = scopeDataStructure.splitPath(path);
-      if (pathParts.length < 3) return false;
 
-      const basePath = scopeDataStructure.joinPathParts([
-        ...pathParts.slice(0, 2),
-        pathParts[2],
-      ]);
+      // Check if this is a direct setter variable call (e.g., setWorkouts(data).signature[0])
+      // rather than a useState path (e.g., useState<X>().functionCallReturnValue[1].signature[0])
+      const fnName = functionCallSignature?.split('(')[0];
+      const isDirectSetterCall = fnName === relevantUseStateInfo.setter;
+
+      if (isDirectSetterCall && pathParts.length === 2) {
+        // Handle direct setter calls like setWorkouts(data || []).signature[0] = data
+        const lastPart = pathParts[1];
+        if (lastPart === 'signature[0]') {
+          // Get the value being passed to the setter from the equivalency
+          const originScopeInfoName =
+            equivalencyValueChain[0]?.currentPath?.scopeNodeName;
+          if (!originScopeInfoName) return propagated;
+
+          const originScope =
+            scopeDataStructure.getScopeOrFunctionCallInfo(originScopeInfoName);
+          const setterCallEquiv = originScope?.equivalencies?.[path];
+          if (!setterCallEquiv || setterCallEquiv.length === 0)
+            return propagated;
+
+          const argumentPath = setterCallEquiv[0].schemaPath;
+          const argumentScopeName = setterCallEquiv[0].scopeNodeName;
+
+          // Create equivalency: useState<X>().functionCallReturnValue[0] = argumentPath
+          propagated = true;
+          const valuePath = `${relevantUseStateInfo.useStateCall}.functionCallReturnValue[0]`;
+          const useStateScopeInfo =
+            scopeDataStructure.getScopeOrFunctionCallInfo(
+              relevantUseStateInfo.scopeNodeName,
+            ) as ScopeNode;
 
-      const expectedSetterBasePath = scopeDataStructure.joinPathParts([
-        functionCallSignature,
-        'functionCallReturnValue[1]',
-      ]);
+          scopeDataStructure.addEquivalency(
+            valuePath,
+            argumentPath,
+            argumentScopeName,
+            useStateScopeInfo,
+            'useState setter call equivalency (direct)',
+            equivalencyValueChain,
+            traceId,
+          );
+        }
+      } else if (pathParts.length >= 3) {
+        // Original logic for useState path patterns
+        const basePath = scopeDataStructure.joinPathParts([
+          ...pathParts.slice(0, 2),
+          pathParts[2],
+        ]);
 
-      // if (traceId) {
-      //   console.info(
-      //     'Debug Propagation: useState base path',
-      //     JSON.stringify(
-      //       {
-      //         traceId,
-      //         basePath,
-      //         expectedValueBasePath,
-      //         expectedSetterBasePath,
-      //       },
-      //       null,
-      //       2,
-      //     ),
-      //   );
-      // }
-
-      if (basePath === expectedSetterBasePath) {
-        const originScopeInfoName =
-          equivalencyValueChain[0].currentPath?.scopeNodeName;
-        const setterScope =
-          scopeDataStructure.getScopeOrFunctionCallInfo(originScopeInfoName);
-        const setterEquivalencyPath = Object.keys(
-          setterScope.equivalencies,
-        ).find((p) => {
-          if (!p.startsWith(relevantUseStateInfo.setter)) return false;
-          const pParts = scopeDataStructure.splitPath(p);
-
-          const valid = pathParts
-            .slice(3)
-            .reverse()
-            .every((part, index) => [...pParts].reverse()[index] === part);
-
-          // if (p.includes('.title') && valid)
-          //   console.info({ p, pParts, pathParts: pathParts.slice(3) });
-
-          return valid;
-        });
-
-        if (!setterEquivalencyPath) return;
-
-        const setterEquivalencyPathParts = scopeDataStructure.splitPath(
-          setterEquivalencyPath,
-        );
-        const setterEquivalentVariable =
-          setterScope.equivalencies[setterEquivalencyPath][0].schemaPath;
+        const expectedSetterBasePath = scopeDataStructure.joinPathParts([
+          functionCallSignature,
+          'functionCallReturnValue[1]',
+        ]);
 
-        if (setterEquivalentVariable === expectedSetterBasePath) return;
+        if (basePath === expectedSetterBasePath) {
+          const originScopeInfoName =
+            equivalencyValueChain[0].currentPath?.scopeNodeName;
+          const setterScope =
+            scopeDataStructure.getScopeOrFunctionCallInfo(originScopeInfoName);
+          const setterEquivalencyPath = Object.keys(
+            setterScope.equivalencies,
+          ).find((p) => {
+            if (!p.startsWith(relevantUseStateInfo.setter)) return false;
+            const pParts = scopeDataStructure.splitPath(p);
+
+            const valid = pathParts
+              .slice(3)
+              .reverse()
+              .every((part, index) => [...pParts].reverse()[index] === part);
+
+            return valid;
+          });
+
+          if (!setterEquivalencyPath) return propagated;
+
+          const setterEquivalencyPathParts = scopeDataStructure.splitPath(
+            setterEquivalencyPath,
+          );
+          const setterEquivalentVariable =
+            setterScope.equivalencies[setterEquivalencyPath][0].schemaPath;
 
-        propagated = true;
-        const valuePath = `${functionCallSignature}.functionCallReturnValue[0]`;
-        const useStateScopeInfo = scopeDataStructure.getScopeOrFunctionCallInfo(
-          relevantUseStateInfo.scopeNodeName,
-        ) as ScopeNode;
+          if (setterEquivalentVariable === expectedSetterBasePath)
+            return propagated;
 
-        const fullValuePath = scopeDataStructure.joinPathParts([
-          valuePath,
-          ...setterEquivalencyPathParts.slice(2),
-        ]);
+          propagated = true;
+          const valuePath = `${functionCallSignature}.functionCallReturnValue[0]`;
+          const useStateScopeInfo =
+            scopeDataStructure.getScopeOrFunctionCallInfo(
+              relevantUseStateInfo.scopeNodeName,
+            ) as ScopeNode;
+
+          const fullValuePath = scopeDataStructure.joinPathParts([
+            valuePath,
+            ...setterEquivalencyPathParts.slice(2),
+          ]);
 
-        scopeDataStructure.addEquivalency(
-          fullValuePath,
-          setterEquivalentVariable,
-          originScopeInfoName,
-          useStateScopeInfo,
-          'useState setter call equivalency',
-          equivalencyValueChain,
-          traceId,
-        );
+          scopeDataStructure.addEquivalency(
+            fullValuePath,
+            setterEquivalentVariable,
+            originScopeInfoName,
+            useStateScopeInfo,
+            'useState setter call equivalency',
+            equivalencyValueChain,
+            traceId,
+          );
+        }
       }
     }
 
@@ -564,6 +634,102 @@ export class ReactFrameworkManager implements EquivalencyManager {
     for (const [equivalentPath, equivalentValues] of Object.entries(
       scopeNode.equivalencies,
     )) {
+      // Check if the equivalency KEY (e.g., "div().signature[0].ref") ends with .ref
+      // If so, the VALUE (e.g., "parent") should be marked as null
+      const equivalentPathParts = scopeDataStructure.splitPath(equivalentPath);
+      const pathLength = equivalentPathParts.length;
+
+      if (pathLength >= 2) {
+        const secondToLast = equivalentPathParts[pathLength - 2];
+        const last = equivalentPathParts[pathLength - 1];
+
+        if (secondToLast === 'signature[0]' && last === 'ref') {
+          // This is a ref prop usage like div().signature[0].ref -> parent
+          for (const equivalentValue of equivalentValues) {
+            propagated = true;
+
+            // Track this variable as a ref - we'll set its type to 'null' in finalize()
+            // after the schema is built (setting directly here would be overwritten)
+            // IMPORTANT: The ref variable might be defined in a parent scope, not the
+            // current scope. We need to find where the variable is actually defined by
+            // walking up the scope tree.
+            const varName = equivalentValue.schemaPath;
+            let targetScope: ScopeNode | null = scopeNode;
+
+            // Walk up the scope tree to find where this variable is defined
+            while (targetScope) {
+              // Check if this scope has the variable in its schema or equivalencies
+              const hasVariable =
+                varName in (targetScope.schema || {}) ||
+                varName in (targetScope.equivalencies || {});
+
+              if (hasVariable) {
+                if (!this.refVariables.has(targetScope.name)) {
+                  this.refVariables.set(targetScope.name, new Set());
+                }
+                this.refVariables.get(targetScope.name)!.add(varName);
+
+                // IMPORTANT: Also update the source of the ref variable in the external
+                // function call's schema. This ensures dataForMocks produces [null]
+                // instead of ["string"] for hooks like useAutoAnimate.
+                const varEquivalencies = targetScope.equivalencies?.[varName];
+                if (varEquivalencies) {
+                  for (const varEquivalency of varEquivalencies) {
+                    const sourcePath = varEquivalency.schemaPath;
+                    // Check if this comes from an external function call
+                    // (contains functionCallReturnValue which indicates it's a hook/function return)
+                    if (sourcePath.includes('functionCallReturnValue')) {
+                      // Store the source path for later - we'll update the external function
+                      // call's schema in finalize() which runs AFTER schema building is complete.
+                      // Setting it here would be overwritten by later schema building.
+                      for (const efc of scopeDataStructure.externalFunctionCalls) {
+                        if (sourcePath.startsWith(efc.name)) {
+                          if (!this.refVariableSources.has(efc.name)) {
+                            this.refVariableSources.set(efc.name, new Set());
+                          }
+                          // Store both the specific indexed path and the generic [] path
+                          this.refVariableSources
+                            .get(efc.name)!
+                            .add(sourcePath);
+                          const genericPath = sourcePath.replace(
+                            /\[\d+\]/g,
+                            '[]',
+                          );
+                          if (genericPath !== sourcePath) {
+                            this.refVariableSources
+                              .get(efc.name)!
+                              .add(genericPath);
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+
+              // Move up to parent scope
+              if (targetScope.tree && targetScope.tree.length > 0) {
+                const parentScopeName =
+                  targetScope.tree[targetScope.tree.length - 1];
+                targetScope = scopeDataStructure.getScopeOrFunctionCallInfo(
+                  parentScopeName,
+                ) as ScopeNode | null;
+              } else {
+                targetScope = null;
+              }
+            }
+
+            scopeDataStructure.removeEquivalency(
+              equivalentPath,
+              equivalentValue,
+              scopeNode,
+            );
+          }
+          continue;
+        }
+      }
+
+      // Original logic for checking the value side
       for (const equivalentValue of equivalentValues) {
         const equivalentValueParts = scopeDataStructure.splitPath(
           equivalentValue.schemaPath,

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

@@ -64,6 +64,14 @@ const protoMethodSets: Record<PrimitiveKind, Set<string>> = {
   ),
 };
 
+/** Built-in properties (not methods) that should be removed from primitives.
+ * These are properties that exist on the prototype and shouldn't appear
+ * as schema entries (they cause malformed mock data structures). */
+const protoPropertySets: Partial<Record<PrimitiveKind, Set<string>>> = {
+  array: new Set(['length']),
+  string: new Set(['length']),
+};
+
 /**
  * Extract primitive kind from a type string, handling union types.
  * E.g., "number | undefined" -> "number", "string | null" -> "string"
@@ -118,11 +126,21 @@ function scrub(
       const rootKind = rootTable.get(prefix);
       if (!rootKind) continue;
 
-      const rawMethod = keyParts[cut].split('(')[0];
+      const rawToken = keyParts[cut];
+      const rawMethod = rawToken.split('(')[0];
+
+      // Check if it's a prototype method (e.g., map, filter, toString)
       if (protoMethodSets[rootKind].has(rawMethod)) {
         onRemove(keyPath);
         break;
       }
+
+      // Check if it's a built-in property (e.g., length on arrays/strings)
+      const propertySet = protoPropertySets[rootKind];
+      if (propertySet && propertySet.has(rawToken)) {
+        onRemove(keyPath);
+        break;
+      }
     }
   }
 }

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

@@ -41,6 +41,19 @@ const isolatingArrayMethodsSet = new Set([
 // Methods that are ambiguous - used on both arrays and non-arrays (e.g., router.push, history.pop)
 // Don't infer array type from these alone without additional evidence
 const ambiguousArrayMethodsSet = new Set(['push', 'pop']);
+
+// Methods that return primitives (boolean, number) - their return values are not mockable
+// These should have their .functionCallReturnValue paths removed from the schema
+const primitiveReturningMethodsSet = new Set([
+  'some', // Returns boolean
+  'every', // Returns boolean
+  'includes', // Returns boolean
+  'indexOf', // Returns number (index)
+  'lastIndexOf', // Returns number (index from end)
+  'findIndex', // Returns number (index)
+  'findLastIndex', // Returns number (index from end)
+]);
+
 export const transformingArrayMethodsSet = new Set([
   'map',
   'reduce',
@@ -106,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';
 
@@ -115,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;
 }
@@ -682,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;
         }
@@ -703,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;
   }
@@ -941,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),
@@ -970,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) {
@@ -984,11 +1072,20 @@ function clearAttributes(
         basePath
       )
         continue;
+      // Preserve functionCallReturnValue for non-string types, UNLESS
+      // the method is a primitive-returning method (like some, every, includes, indexOf)
+      // whose return values are not mockable
+      const methodPart = keyParts[basePathParts.length];
+      const methodName = methodPart?.split('(')[0];
+      const isPrimitiveReturning = primitiveReturningMethodsSet.has(
+        methodName ?? '',
+      );
       if (
         mapping[basePath] !== 'string' &&
         keyParts[basePathParts.length + 1]?.startsWith(
           'functionCallReturnValue',
-        )
+        ) &&
+        !isPrimitiveReturning
       )
         continue;
 

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

@@ -6,6 +6,14 @@ const STANDALONE_INDEX_RE = /^\[(\d+)\]$/;
 const isExplicitIndex = (s?: string) => !!s && INDEXED_RE.test(s);
 const isStandaloneIndex = (s?: string) => !!s && STANDALONE_INDEX_RE.test(s);
 
+// Detect .length properties that come from dynamic iteration patterns
+// These aren't useful for mock data - arrays work without explicit length,
+// and objects shouldn't have length. We filter .length that appears:
+// 1. After array notation: metadata[].length, items[][].length
+// 2. On object paths that likely come from iteration: metadata.length (when metadata has other props)
+// The regex matches any path ending with .length that has [] somewhere before it
+const DYNAMIC_LENGTH_RE = /\[\].*\.length$/;
+
 // Treat these as structural placeholders (don't commit them as concrete leaves)
 function isSkippableLeafType(t: string) {
   // 'unknown' by itself is a placeholder (but 'boolean | unknown' is not)
@@ -23,6 +31,10 @@ export default function convertDotNotation(
   const result: JsonTypeDefinition = {};
 
   for (const [rawPath, typ] of Object.entries(schema)) {
+    // Skip paths with .length after array notation from dynamic iteration
+    // e.g., metadata[].length, metadata[][].length
+    if (DYNAMIC_LENGTH_RE.test(rawPath)) continue;
+
     const parts = splitOutsideParenthesesAndArrays(rawPath);
     if (!parts || parts.length === 0) continue;
 
@@ -187,6 +199,17 @@ export default function convertDotNotation(
           i++; // consume '[]'
         } else {
           // Pattern like: "items", "[]", "id" -> items: [ { id: ... } ]
+          // But if cursor[key] is already a non-array object (from paths like "metadata: object"),
+          // don't overwrite it with an array - the object type should take precedence.
+          // This handles spurious "metadata[]" paths from dynamic iteration (Object.keys, for...in).
+          if (
+            cursor[key] !== undefined &&
+            typeof cursor[key] === 'object' &&
+            !Array.isArray(cursor[key])
+          ) {
+            // Skip this path - it's trying to treat an object as an array
+            break;
+          }
           if (!Array.isArray(cursor[key])) cursor[key] = [];
 
           // Look ahead to see what comes after '[]'