@codeyam/codeyam-cli 0.1.0-staging.1 → 0.1.0-staging.596f0eb

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

@@ -0,0 +1,235 @@
+/**
+ * VisitedTracker
+ *
+ * Manages visited state tracking for the ScopeDataStructure analysis.
+ * Prevents infinite loops and redundant processing by tracking which
+ * scope/path/value combinations have already been processed.
+ *
+ * ## Why This Exists
+ *
+ * The schema building process recursively follows equivalencies between
+ * data paths. Without cycle detection, circular references like:
+ *   `user.profile` → `currentUser` → `user.profile`
+ * would cause infinite loops.
+ *
+ * ## Two Tracking Modes
+ *
+ * ### 1. Global Visited (scope::path::value)
+ * Fine-grained deduplication for `addToSchema()`. Tracks the complete
+ * tuple so the same path can be visited with different type values.
+ *
+ * Example: `myFunc::user.id::string` and `myFunc::user.id::number`
+ * are tracked separately, allowing both types to be recorded.
+ *
+ * ### 2. Complex Source Visited (scope::path)
+ * Coarser deduplication for `addComplexSourcePathVariables()`. Ignores
+ * the type value because complex source processing should happen once
+ * per path regardless of type.
+ *
+ * ## Lifecycle
+ *
+ * - Global visited is **reset** at the start of `captureCompleteSchema()`
+ *   to allow re-processing in the schema building phase.
+ * - Complex source visited is **never reset** during normal operation.
+ *
+ * ## Related Modules
+ *
+ * - `ScopeDataStructure.addToSchema()` - Primary consumer of global visited
+ * - `ScopeDataStructure.addComplexSourcePathVariables()` - Uses complex source visited
+ */
+
+/**
+ * Tracks visited state to prevent infinite loops during schema building.
+ */
+export class VisitedTracker {
+  /**
+   * Fine-grained visited tracking using scope::path::value.
+   * Used by addToSchema to skip already-processed combinations.
+   */
+  private globalVisited: Set<string> = new Set();
+
+  /**
+   * Coarser visited tracking using scope::path only (without value).
+   * Used by addComplexSourcePathVariables to allow each unique
+   * scope+path combo to be processed once, regardless of value.
+   */
+  private complexSourceVisited: Set<string> = new Set();
+
+  /**
+   * Creates a unique key for global visited tracking.
+   * @param scopeNodeName - Name of the scope
+   * @param path - Schema path
+   * @param value - Type value
+   */
+  private makeGlobalKey(
+    scopeNodeName: string,
+    path: string,
+    value: string,
+  ): string {
+    return `${scopeNodeName}::${path}::${value}`;
+  }
+
+  /**
+   * Creates a unique key for complex source visited tracking.
+   * @param scopeNodeName - Name of the scope
+   * @param path - Schema path
+   */
+  private makeComplexKey(scopeNodeName: string, path: string): string {
+    return `${scopeNodeName}::${path}`;
+  }
+
+  /**
+   * Checks if a scope/path/value combination has been globally visited.
+   * Does NOT mark it as visited - use markGlobalVisited for that.
+   *
+   * @returns true if already visited
+   */
+  hasGlobalVisited(
+    scopeNodeName: string,
+    path: string,
+    value: string,
+  ): boolean {
+    return this.globalVisited.has(
+      this.makeGlobalKey(scopeNodeName, path, value),
+    );
+  }
+
+  /**
+   * Marks a scope/path/value combination as globally visited.
+   */
+  markGlobalVisited(scopeNodeName: string, path: string, value: string): void {
+    this.globalVisited.add(this.makeGlobalKey(scopeNodeName, path, value));
+  }
+
+  /**
+   * Checks and marks a scope/path/value combination as globally visited.
+   * This is a convenience method that combines check and mark.
+   *
+   * @returns true if was already visited (should skip processing)
+   */
+  checkAndMarkGlobalVisited(
+    scopeNodeName: string,
+    path: string,
+    value: string,
+  ): boolean {
+    const key = this.makeGlobalKey(scopeNodeName, path, value);
+    if (this.globalVisited.has(key)) {
+      return true; // Already visited
+    }
+    this.globalVisited.add(key);
+    return false; // Not visited, now marked
+  }
+
+  /**
+   * Checks if a scope/path combination has been visited for complex sources.
+   * Does NOT mark it as visited - use markComplexSourceVisited for that.
+   *
+   * @returns true if already visited
+   */
+  hasComplexSourceVisited(scopeNodeName: string, path: string): boolean {
+    return this.complexSourceVisited.has(
+      this.makeComplexKey(scopeNodeName, path),
+    );
+  }
+
+  /**
+   * Marks a scope/path combination as visited for complex sources.
+   */
+  markComplexSourceVisited(scopeNodeName: string, path: string): void {
+    this.complexSourceVisited.add(this.makeComplexKey(scopeNodeName, path));
+  }
+
+  /**
+   * Checks and marks a scope/path combination as visited for complex sources.
+   * This is a convenience method that combines check and mark.
+   *
+   * @returns true if was already visited (should skip processing)
+   */
+  checkAndMarkComplexSourceVisited(
+    scopeNodeName: string,
+    path: string,
+  ): boolean {
+    const key = this.makeComplexKey(scopeNodeName, path);
+    if (this.complexSourceVisited.has(key)) {
+      return true; // Already visited
+    }
+    this.complexSourceVisited.add(key);
+    return false; // Not visited, now marked
+  }
+
+  /**
+   * Resets the global visited set.
+   * Called at the start of captureCompleteSchema() to allow
+   * re-processing in the second phase.
+   */
+  resetGlobalVisited(): void {
+    this.globalVisited.clear();
+  }
+
+  /**
+   * Resets the complex source visited set.
+   * Note: In the original code, this was never reset.
+   */
+  resetComplexSourceVisited(): void {
+    this.complexSourceVisited.clear();
+  }
+
+  /**
+   * Resets all visited tracking.
+   */
+  resetAll(): void {
+    this.globalVisited.clear();
+    this.complexSourceVisited.clear();
+  }
+
+  /**
+   * Returns statistics about the visited sets for debugging/monitoring.
+   */
+  getStats(): { globalVisited: number; complexSourceVisited: number } {
+    return {
+      globalVisited: this.globalVisited.size,
+      complexSourceVisited: this.complexSourceVisited.size,
+    };
+  }
+
+  /**
+   * Checks if ANY variant of a scope/path was ever visited (ignores value).
+   * Useful for debugging to see if a path was processed at all.
+   *
+   * @returns true if any variant of this scope/path was visited
+   */
+  wasVisited(scopeNodeName: string, path: string): boolean {
+    const prefix = `${scopeNodeName}::${path}::`;
+    for (const key of this.globalVisited) {
+      if (key.startsWith(prefix)) {
+        return true;
+      }
+    }
+    return this.hasComplexSourceVisited(scopeNodeName, path);
+  }
+
+  /**
+   * Gets all visited entries for a scope (for debugging).
+   * Returns an array of {path, value} objects.
+   */
+  getVisitedForScope(
+    scopeNodeName: string,
+  ): Array<{ path: string; value: string }> {
+    const prefix = `${scopeNodeName}::`;
+    const results: Array<{ path: string; value: string }> = [];
+
+    for (const key of this.globalVisited) {
+      if (key.startsWith(prefix)) {
+        const parts = key.slice(prefix.length).split('::');
+        if (parts.length >= 2) {
+          results.push({
+            path: parts.slice(0, -1).join('::'), // Everything except last part
+            value: parts[parts.length - 1], // Last part is value
+          });
+        }
+      }
+    }
+
+    return results;
+  }
+}

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

@@ -30,7 +30,13 @@ export const nonTransformingArrayMethodsSet = new Set([
   'reverse',
   'entries',
 ]);
-const isolatingArrayMethodsSet = new Set(['find', 'at', 'pop', 'shift']);
+const isolatingArrayMethodsSet = new Set([
+  'find',
+  'findLast', // Returns element like find, but from end
+  'at',
+  'pop',
+  'shift',
+]);
 
 // 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
@@ -42,6 +48,12 @@ export const transformingArrayMethodsSet = new Set([
   'concat',
   'join',
   'some',
+  'every', // Returns boolean
+  'findIndex', // Returns number (index)
+  'findLastIndex', // Returns number (index from end)
+  'indexOf', // Returns number (index)
+  'lastIndexOf', // Returns number (index from end)
+  'includes', // Returns boolean
 ]);
 
 export const arrayMethodsSet = new Set([
@@ -225,6 +237,54 @@ export function clearAttributesFromMapping(
   clearAttributes(mapping, knownBasePaths);
 }
 
+/**
+ * Remove duplicate function calls (same function with different arguments) that have no return data.
+ * Example: setSelectedFilter(arg1) and setSelectedFilter(arg2) where neither has functionCallReturnValue
+ * These create invalid mock code when spread together (orphan spread statements).
+ *
+ * This is a targeted fix that can be called independently without the full clearAttributes logic,
+ * which was disabled in constructMockCode.ts due to side effects on array method calls.
+ */
+export function removeDuplicateFunctionCalls(
+  mapping: Record<string, string>,
+): void {
+  const allKeys = Object.keys(mapping);
+  const functionCallGroups: { [baseName: string]: string[] } = {};
+
+  for (const key of allKeys) {
+    // Only process paths that:
+    // 1. Are marked as 'function'
+    // 2. END with a function call (parentheses) - not just contain one somewhere
+    // 3. Are on an object path (contain '.')
+    if (mapping[key] === 'function' && key.endsWith(')') && key.includes('.')) {
+      // Extract base path + function name (without the arguments)
+      // e.g., "returnValue.setSelectedFilter(arg)" -> "returnValue.setSelectedFilter"
+      const baseName = key.replace(/\([^)]*\)$/, '');
+      functionCallGroups[baseName] ||= [];
+      functionCallGroups[baseName].push(key);
+    }
+  }
+
+  // For groups with multiple calls (same function, different args), remove those without return data
+  for (const baseName in functionCallGroups) {
+    const calls = functionCallGroups[baseName];
+    if (calls.length > 1) {
+      // Multiple calls to the same function with different arguments
+      for (const callPath of calls) {
+        // Check if this call has return data
+        const hasReturnData = allKeys.some(
+          (k: string) =>
+            k.startsWith(callPath + '.functionCallReturnValue') ||
+            k.startsWith(callPath + '.signature['),
+        );
+        if (!hasReturnData) {
+          delete mapping[callPath];
+        }
+      }
+    }
+  }
+}
+
 function transformPath({
   oldPath,
   newPath,
@@ -642,13 +702,16 @@ 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
     const methodName = getMethodName(lastPart);
     const isAmbiguousMethod = ambiguousArrayMethodsSet.has(methodName);
+    const isStringType = keyMapping[previousPath] === 'string';
     if (
       !isValidFunctionCall(previousPart) &&
       arrayMethodsSet.has(methodName) &&
       !keyMapping[previousPath + '[]'] &&
-      !isAmbiguousMethod
+      !isAmbiguousMethod &&
+      !isStringType
     ) {
       keyMapping[previousPath + '[]'] = 'unknown';
     }
@@ -901,6 +964,9 @@ function clearAttributes(
     }
   }
 
+  // Remove duplicate function calls (same function with different arguments) that have no return data
+  removeDuplicateFunctionCalls(mapping);
+
   for (const key in mapping) {
     const value = mapping[key];
     if (knownTypes.has(value)) {

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

@@ -26,7 +26,6 @@ export default function convertDotNotation(
     const parts = splitOutsideParenthesesAndArrays(rawPath);
     if (!parts || parts.length === 0) continue;
 
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     let cursor: any = result;
 
     for (let i = 0; i < parts.length; i++) {
@@ -181,8 +180,9 @@ export default function convertDotNotation(
           if (!isSkippableLeafType(typ)) {
             cursor[key] = [typ];
           } else {
-            // structural/placeholder subtype — ensure array exists but don't clobber
-            if (!Array.isArray(cursor[key])) cursor[key] = [];
+            // structural/placeholder subtype — ensure array exists but don't clobber existing values
+            // Only create an array if nothing exists yet; preserve concrete types like 'string'
+            if (cursor[key] === undefined) cursor[key] = [];
           }
           i++; // consume '[]'
         } else {

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

@@ -355,9 +355,11 @@ export function fillInDirectSchemaGapsAndUnknowns({
 
           // Don't set to 'function' if this is a promise method on an async function
           // (we want the awaited value, not the promise)
+          // Also don't overwrite 'array' - the function might return an array (e.g., getAll())
           if (
             schema[functionReturnValuePath] &&
             schema[functionReturnValuePath] !== 'function' &&
+            schema[functionReturnValuePath] !== 'array' &&
             !(isPromiseMethod && isPreviousAsync)
           ) {
             schema[functionReturnValuePath] = 'function';
@@ -408,17 +410,26 @@ function checkIfObjectOrFunction(path: string, schema: ScopeNode['schema']) {
   }
 }
 
-// Methods that are ambiguous - used on both arrays and non-arrays (e.g., router.push, history.pop)
+// Methods that are ambiguous - used on both arrays and non-arrays
+// These methods exist on arrays but also on Map, Set, Headers, FormData, URLSearchParams, etc.
 // Don't infer array type from these alone without additional evidence
-const AMBIGUOUS_ARRAY_METHODS = new Set(['push', 'pop']);
+const AMBIGUOUS_ARRAY_METHODS = new Set([
+  'push',
+  'pop',
+  'entries',
+  'keys',
+  'values',
+  'forEach',
+]);
 
 // Methods that are strongly indicative of arrays - only arrays have these
+// Note: entries, keys, values, forEach are NOT in this list because they also exist
+// on Map, Set, Headers, FormData, URLSearchParams, and other iterable types
 const STRONG_ARRAY_METHODS = new Set([
   'map',
   'filter',
   'reduce',
   'reduceRight',
-  'forEach',
   'every',
   'some',
   'find',
@@ -429,9 +440,6 @@ const STRONG_ARRAY_METHODS = new Set([
   'flatMap',
   'fill',
   'copyWithin',
-  'entries',
-  'keys',
-  'values',
   'toReversed',
   'toSorted',
   'toSpliced',
@@ -446,6 +454,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] ??
     []) {
@@ -459,11 +469,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;
     }
 
@@ -487,10 +504,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/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/dataStructure/helpers/selectBestValue.ts

@@ -0,0 +1,70 @@
+/**
+ * selectBestValue
+ *
+ * Selects the most specific type value from two candidates.
+ * Prefers more specific types over 'unknown' values.
+ *
+ * ## Context
+ *
+ * During schema building, the same path may have type information from
+ * multiple sources (e.g., from a return statement and from a function call).
+ * When merging these, we want to keep the most specific type.
+ *
+ * "Specific" means:
+ * - `'string'` is more specific than `'unknown'`
+ * - `'string'` is more specific than `'unknown|string'`
+ * - `'string|number'` is equal specificity to `'number|string'`
+ *
+ * ## Selection Rules
+ *
+ * 1. If value1 exists and is not 'unknown', use value1
+ * 2. If value2 exists and is more specific (not 'unknown'), prefer value2
+ * 3. Otherwise use the first available value, or 'unknown' as default
+ *
+ * ## Where Used
+ *
+ * - `propagateSourceAndUsageEquivalencies.equateSchema()` - Merging schemas
+ * - `getReturnValue()` - Combining return type information
+ *
+ * ## Related Modules
+ *
+ * - `ensureSchemaConsistency.ts` - Also deals with type merging
+ * - `fillInSchemaGapsAndUnknowns.ts` - Fills in missing types after schema building
+ */
+
+/**
+ * Selects the best (most specific) value between two type candidates.
+ *
+ * @param value1 - Primary value (preferred if specific)
+ * @param value2 - Secondary value (used if value1 is 'unknown')
+ * @param defaultValue - Default when both are undefined (defaults to 'unknown')
+ * @returns The most specific type value
+ *
+ * @example
+ * selectBestValue('string', 'number') // 'string' - value1 is specific
+ * selectBestValue('unknown', 'string') // 'string' - value2 is more specific
+ * selectBestValue(undefined, 'number') // 'number' - value1 undefined
+ * selectBestValue(undefined, undefined) // 'unknown' - default
+ * selectBestValue('unknown|string', 'string') // 'string' - value2 has no unknown
+ */
+export default function selectBestValue(
+  value1: string | undefined,
+  value2: string | undefined,
+  defaultValue = 'unknown',
+): string {
+  let bestValue = value1 ?? value2 ?? defaultValue;
+
+  // Prefer value2 if:
+  // - value2 exists AND
+  // - bestValue is 'unknown' and value2 is not, OR
+  // - bestValue contains 'unknown' and value2 doesn't
+  if (
+    value2 &&
+    ((bestValue === 'unknown' && value2 !== 'unknown') ||
+      (bestValue.includes('unknown') && !value2.includes('unknown')))
+  ) {
+    bestValue = value2;
+  }
+
+  return bestValue;
+}