@codeyam/codeyam-cli 0.1.0-staging.8aea589 → 0.1.0-staging.8df382d

package/analyzer-template/packages/ai/src/lib/astScopes/methodSemantics.ts

@@ -139,6 +139,96 @@ export class ArrayFilterSemantics implements MethodSemantics {
   }
 }
 
+/**
+ * Array some method semantics
+ *
+ * some() returns true if at least one element passes the test, false otherwise
+ * The callback receives array elements to test
+ */
+export class ArraySomeSemantics implements MethodSemantics {
+  getReturnType(): string {
+    return 'boolean';
+  }
+
+  addEquivalences(
+    methodCallPath: StructuredPath,
+    sourcePath: StructuredPath,
+    context: AnalysisContext,
+  ): void {
+    // Mark source as array
+    context.addType(sourcePath, 'array');
+
+    // Mark return as boolean
+    context.addType(methodCallPath, 'boolean');
+
+    // Get the last function call segment to access the arguments
+    const lastFunctionCallSegment = methodCallPath.getLastFunctionCallSegment();
+
+    if (lastFunctionCallSegment && lastFunctionCallSegment.args.length > 0) {
+      // The first argument is the callback
+      const callbackPath = lastFunctionCallSegment.args[0];
+
+      // Add the callback to the structure
+      context.addType(callbackPath, 'function');
+
+      // Mark that the callback's first parameter receives array elements
+      context.addEquivalence(
+        callbackPath.withParameter(0),
+        sourcePath.withElement('*'),
+      );
+    }
+  }
+
+  isComplete(): boolean {
+    return true;
+  }
+}
+
+/**
+ * Array every method semantics
+ *
+ * every() returns true if all elements pass the test, false otherwise
+ * The callback receives array elements to test
+ */
+export class ArrayEverySemantics implements MethodSemantics {
+  getReturnType(): string {
+    return 'boolean';
+  }
+
+  addEquivalences(
+    methodCallPath: StructuredPath,
+    sourcePath: StructuredPath,
+    context: AnalysisContext,
+  ): void {
+    // Mark source as array
+    context.addType(sourcePath, 'array');
+
+    // Mark return as boolean
+    context.addType(methodCallPath, 'boolean');
+
+    // Get the last function call segment to access the arguments
+    const lastFunctionCallSegment = methodCallPath.getLastFunctionCallSegment();
+
+    if (lastFunctionCallSegment && lastFunctionCallSegment.args.length > 0) {
+      // The first argument is the callback
+      const callbackPath = lastFunctionCallSegment.args[0];
+
+      // Add the callback to the structure
+      context.addType(callbackPath, 'function');
+
+      // Mark that the callback's first parameter receives array elements
+      context.addEquivalence(
+        callbackPath.withParameter(0),
+        sourcePath.withElement('*'),
+      );
+    }
+  }
+
+  isComplete(): boolean {
+    return true;
+  }
+}
+
 /**
  * Array find method semantics
  *
@@ -173,12 +263,12 @@ export class ArrayFindSemantics implements MethodSemantics {
         sourcePath.withElement('*'),
       );
 
-      // THIS IS PRODUCING STRANGE RESULTS SUCH AS
-      // 'people.filter(cyScope2()).find(cyScope3())': 'people.filter(cyScope2()).functionCallReturnValue[]',
-      // 'personWithHome.places.find(cyScope5())': 'personWithHome.places[]'
-      // WHICH DO NOT MAKES SENSE
-      // REMOVING BUT LEAVING IN PLACE IN CASE THERE IS A VALID USE CASE
-      // The result is an element from the array that matches the callback condition
+      // NOTE: We intentionally do NOT create an equivalency from the find result
+      // to the array element here. While semantically correct (find returns an element),
+      // doing so causes type inference issues where the array element gets typed as
+      // 'function' instead of 'object'. The tracing back to source arrays happens
+      // through the || operator processing and null guard in addEquivalence.
+      // See: analyzeScopeNoAI1.test.ts for tests that break if this is uncommented.
       // context.addEquivalence(methodCallPath, sourcePath.withElement('*'));
     }
   }
@@ -239,11 +329,17 @@ export class ArrayReduceSemantics implements MethodSemantics {
 /**
  * Array concat method semantics
  *
- * concat() returns a new array combining the original array and additional items
+ * concat() returns a new array/string combining the original and additional items
+ *
+ * NOTE: We intentionally do NOT type the source as 'array' here because
+ * .concat() exists on both arrays AND strings. Typing the source prematurely
+ * causes type contamination when the source is equivalent to other paths
+ * via ?? chains. Type inference happens later in checkIfKnownType() based
+ * on accumulated evidence from all methods called on a path.
  */
 export class ArrayConcatSemantics implements MethodSemantics {
   getReturnType(): string {
-    return 'array';
+    return 'unknown'; // Could be array or string depending on source
   }
 
   addEquivalences(
@@ -251,23 +347,24 @@ export class ArrayConcatSemantics implements MethodSemantics {
     sourcePath: StructuredPath,
     context: AnalysisContext,
   ): void {
-    // Mark source as array
-    context.addType(sourcePath, 'array');
+    // NOTE: We use 'unknown' instead of 'array' for the source because .concat()
+    // exists on both arrays AND strings. Using 'array' causes type contamination
+    // when the source is equivalent to other paths via ?? chains.
+    context.addType(sourcePath, 'unknown');
 
-    // Any arguments are also added to the array
+    // Any arguments are also added to the result
     const functionCallSegment = methodCallPath.getLastFunctionCallSegment();
 
     if (functionCallSegment) {
       // Each argument could be an array or single element
       functionCallSegment.args.forEach((argPath) => {
         // No need to guess the type - we'll discover it through normal processing
-        // But we can indicate that these elements will be in the result array
+        // But we can indicate that these elements will be in the result
         context.addEquivalence(methodCallPath, argPath);
       });
     }
 
-    // The original array elements are also in the result
-    context.addType(methodCallPath, 'array');
+    // The original elements are also in the result
     context.addEquivalence(methodCallPath, sourcePath.withElement('*'));
   }
 
@@ -279,11 +376,17 @@ export class ArrayConcatSemantics implements MethodSemantics {
 /**
  * Array slice method semantics
  *
- * slice() returns a shallow copy of a portion of an array
+ * slice() returns a shallow copy of a portion of an array (or string)
+ *
+ * NOTE: We intentionally do NOT type the source as 'array' here because
+ * .slice() exists on both arrays AND strings. Typing the source prematurely
+ * causes type contamination when the source is equivalent to other paths
+ * via ?? chains. Type inference happens later in checkIfKnownType() based
+ * on accumulated evidence from all methods called on a path.
  */
 export class ArraySliceSemantics implements MethodSemantics {
   getReturnType(): string {
-    return 'array';
+    return 'unknown'; // Could be array or string depending on source
   }
 
   addEquivalences(
@@ -291,12 +394,15 @@ export class ArraySliceSemantics implements MethodSemantics {
     sourcePath: StructuredPath,
     context: AnalysisContext,
   ): void {
-    // Mark source as array
-    context.addType(sourcePath, 'array');
+    // NOTE: We use 'unknown' instead of 'array' for the source because .slice()
+    // exists on both arrays AND strings. Using 'array' causes type contamination
+    // when the source is equivalent to other paths via ?? chains.
+    // Type inference happens later in checkIfKnownType() based on accumulated evidence.
+    context.addType(sourcePath, 'unknown');
 
-    // The elements in the result are the same type as the source array
+    // Still track the return value type for data structure tracking
     const methodCallPathWithReturnValues = methodCallPath.withReturnValues();
-    context.addType(methodCallPathWithReturnValues, 'array');
+    context.addType(methodCallPathWithReturnValues, 'unknown');
   }
 
   isComplete(): boolean {
@@ -343,6 +449,56 @@ export class ArraySpliceSemantics implements MethodSemantics {
   }
 }
 
+/**
+ * Array push method semantics
+ *
+ * push() adds one or more elements to the end of an array and returns the new length.
+ * Critically for data flow analysis, pushed elements become array elements.
+ */
+export class ArrayPushSemantics implements MethodSemantics {
+  getReturnType(): string {
+    return 'number'; // push returns the new length of the array
+  }
+
+  addEquivalences(
+    methodCallPath: StructuredPath,
+    sourcePath: StructuredPath,
+    context: AnalysisContext,
+  ): void {
+    // Mark source as array
+    context.addType(sourcePath, 'array');
+
+    // Get the last function call segment to access the arguments
+    const functionCallSegment = methodCallPath.getLastFunctionCallSegment();
+
+    if (functionCallSegment && functionCallSegment.args.length > 0) {
+      // Each argument is an element being added to the array
+      // Establish equivalence: array[] === pushed element
+      // This enables tracing through patterns like:
+      //   allEntities.push({...entity})
+      //   allEntities.map(e => e.prop) // e.prop traces back to entity.prop
+      //
+      // We use methodCallPath.withParameter(i) because that's the path used when
+      // processExpression processes each argument. The spread equivalencies are
+      // set up against signature[i] paths, so we need to connect to those.
+      //
+      // Note: The path transformation in paths.ts now correctly handles the case
+      // where .signature[n] follows a function call - it won't add
+      // .functionCallReturnValue before the parameter path.
+      for (let i = 0; i < functionCallSegment.args.length; i++) {
+        context.addEquivalence(
+          sourcePath.withElement('*'),
+          methodCallPath.withParameter(i),
+        );
+      }
+    }
+  }
+
+  isComplete(): boolean {
+    return true;
+  }
+}
+
 /**
  * Array join method semantics
  *
@@ -423,6 +579,241 @@ export class ArrayMapSemantics implements MethodSemantics {
   }
 }
 
+/**
+ * Array flatMap method semantics
+ *
+ * flatMap() maps each element using a mapping function, then flattens the result into a new array
+ */
+export class ArrayFlatMapSemantics implements MethodSemantics {
+  getReturnType(): string {
+    return 'array';
+  }
+
+  addEquivalences(
+    methodCallPath: StructuredPath,
+    sourcePath: StructuredPath,
+    context: AnalysisContext,
+  ): void {
+    // Mark source as array
+    context.addType(sourcePath, 'array');
+
+    // Get the last function call segment to access the arguments
+    const lastFunctionCallSegment = methodCallPath.getLastFunctionCallSegment();
+
+    if (lastFunctionCallSegment && lastFunctionCallSegment.args.length > 0) {
+      // The first argument is the callback
+      const callbackPath = lastFunctionCallSegment.args[0];
+
+      // Add the callback to the structure
+      context.addType(callbackPath, 'function');
+
+      // Mark that the callback's first parameter receives array elements
+      context.addEquivalence(
+        callbackPath.withParameter(0),
+        sourcePath.withElement('*'),
+      );
+    }
+  }
+
+  isComplete(): boolean {
+    return true;
+  }
+}
+
+/**
+ * Array at method semantics
+ *
+ * at() returns the element at the given index, supporting negative indices
+ *
+ * NOTE: We intentionally do NOT type the source as 'array' here because
+ * .at() exists on both arrays AND strings. Typing the source prematurely
+ * causes type contamination when the source is equivalent to other paths
+ * via ?? chains. Type inference happens later in checkIfKnownType() based
+ * on accumulated evidence from all methods called on a path.
+ */
+export class ArrayAtSemantics implements MethodSemantics {
+  getReturnType(): string {
+    return 'unknown'; // Returns element type or undefined
+  }
+
+  addEquivalences(
+    methodCallPath: StructuredPath,
+    sourcePath: StructuredPath,
+    context: AnalysisContext,
+  ): void {
+    // NOTE: We use 'unknown' instead of 'array' for the source because .at()
+    // exists on both arrays AND strings. Using 'array' causes type contamination
+    // when the source is equivalent to other paths via ?? chains.
+    context.addType(sourcePath, 'unknown');
+
+    // The return value is equivalent to an element
+    context.addEquivalence(
+      methodCallPath.withReturnValues(),
+      sourcePath.withElement('*'),
+    );
+  }
+
+  isComplete(): boolean {
+    return true;
+  }
+}
+
+/**
+ * Array findLast method semantics
+ *
+ * findLast() returns the last element that passes the test, or undefined
+ */
+export class ArrayFindLastSemantics implements MethodSemantics {
+  getReturnType(): string {
+    return 'unknown'; // Could be any type from the array or undefined
+  }
+
+  addEquivalences(
+    methodCallPath: StructuredPath,
+    sourcePath: StructuredPath,
+    context: AnalysisContext,
+  ): void {
+    // Mark source as array
+    context.addType(sourcePath, 'array');
+
+    // Get the last function call segment to access the arguments
+    const functionCallSegment = methodCallPath.getLastFunctionCallSegment();
+
+    if (functionCallSegment && functionCallSegment.args.length > 0) {
+      // The first argument is the callback
+      const callbackPath = functionCallSegment.args[0];
+
+      // Add the callback to the structure
+      context.addType(callbackPath, 'function');
+
+      // Mark that the callback's first parameter receives array elements
+      context.addEquivalence(
+        callbackPath.withParameter(0),
+        sourcePath.withElement('*'),
+      );
+    }
+  }
+
+  isComplete(): boolean {
+    return true;
+  }
+}
+
+/**
+ * Object.fromEntries method semantics
+ *
+ * fromEntries() transforms a list of key-value pairs into an object
+ */
+export class ObjectFromEntriesSemantics implements MethodSemantics {
+  getReturnType(): string {
+    return 'object';
+  }
+
+  addEquivalences(
+    methodCallPath: StructuredPath,
+    sourcePath: StructuredPath,
+    context: AnalysisContext,
+  ): void {
+    // The source path would be Object, not particularly useful
+    // The argument is an iterable of key-value pairs
+    const functionCallSegment = methodCallPath.getLastFunctionCallSegment();
+
+    if (functionCallSegment && functionCallSegment.args.length > 0) {
+      // Mark the argument as an array (iterable of entries)
+      const entriesPath = functionCallSegment.args[0];
+      context.addType(entriesPath, 'array');
+    }
+  }
+
+  isComplete(): boolean {
+    return true;
+  }
+}
+
+/**
+ * String split method semantics
+ *
+ * split() returns an array of strings by splitting the source string on a delimiter.
+ * This is commonly used for URL path parsing: splat?.split('/') → segments[]
+ *
+ * Important for controllability: if the source string is controllable (e.g., from useParams()),
+ * then the resulting array elements are also controllable.
+ */
+export class StringSplitSemantics implements MethodSemantics {
+  getReturnType(): string {
+    return 'string[]';
+  }
+
+  addEquivalences(
+    methodCallPath: StructuredPath,
+    sourcePath: StructuredPath,
+    context: AnalysisContext,
+  ): void {
+    // Mark source as string
+    context.addType(sourcePath, 'string');
+
+    // Mark the result as a string array
+    context.addType(methodCallPath, 'string[]');
+
+    // Establish equivalence: each element of the result derives from the source string
+    // This enables controllability tracking: if sourcePath is controllable,
+    // then methodCallPath[] elements are controllable via the same mock
+    context.addEquivalence(
+      methodCallPath.withReturnValues().withElement('*'),
+      sourcePath,
+    );
+  }
+
+  isComplete(): boolean {
+    return true;
+  }
+}
+
+/**
+ * Promise.then method semantics
+ *
+ * then() registers a callback to be called when the promise resolves,
+ * and returns a new promise that resolves to the callback's return value
+ */
+export class PromiseThenSemantics implements MethodSemantics {
+  getReturnType(): string {
+    return 'unknown'; // Returns a Promise resolving to the callback's return
+  }
+
+  addEquivalences(
+    methodCallPath: StructuredPath,
+    sourcePath: StructuredPath,
+    context: AnalysisContext,
+  ): void {
+    // Get the callback argument
+    const functionCallSegment = methodCallPath.getLastFunctionCallSegment();
+
+    if (functionCallSegment && functionCallSegment.args.length > 0) {
+      const callbackPath = functionCallSegment.args[0];
+
+      // Mark the callback as a function
+      context.addType(callbackPath, 'function');
+
+      // The callback's first parameter receives the resolved value of the source promise
+      // For promise.then(response => ...), response = promise's resolved value
+      // Note: Don't add .functionCallReturnValue - the system adds it automatically
+      // via toRightHandSideString() when storing equivalences
+      context.addEquivalence(callbackPath.withParameter(0), sourcePath);
+
+      // The .then() return value (when chained) resolves to the callback's return
+      // This enables chained .then() calls to track through
+      context.addEquivalence(
+        methodCallPath.withProperty('functionCallReturnValue'),
+        callbackPath.withProperty('returnValue'),
+      );
+    }
+  }
+
+  isComplete(): boolean {
+    return true;
+  }
+}
+
 /**
  * UseMemo React hook semantics
  *
@@ -513,12 +904,27 @@ export function createMethodRegistry(): MethodSemanticsRegistry {
   // Register array methods
   registry.register('filter', new ArrayFilterSemantics(), 'Array');
   registry.register('map', new ArrayMapSemantics(), 'Array');
+  registry.register('flatMap', new ArrayFlatMapSemantics(), 'Array');
   registry.register('join', new ArrayJoinSemantics(), 'Array');
   registry.register('find', new ArrayFindSemantics(), 'Array');
+  registry.register('findLast', new ArrayFindLastSemantics(), 'Array');
+  registry.register('at', new ArrayAtSemantics(), 'Array');
   registry.register('reduce', new ArrayReduceSemantics(), 'Array');
   registry.register('concat', new ArrayConcatSemantics(), 'Array');
   registry.register('slice', new ArraySliceSemantics(), 'Array');
   registry.register('splice', new ArraySpliceSemantics(), 'Array');
+  registry.register('push', new ArrayPushSemantics(), 'Array');
+  registry.register('some', new ArraySomeSemantics(), 'Array');
+  registry.register('every', new ArrayEverySemantics(), 'Array');
+
+  // Register Object methods
+  registry.register('fromEntries', new ObjectFromEntriesSemantics(), 'Object');
+
+  // Register String methods
+  registry.register('split', new StringSplitSemantics(), 'String');
+
+  // Register Promise methods
+  registry.register('then', new PromiseThenSemantics(), 'Promise');
 
   // Register React hooks
   registry.register('useState', new UseStateSemantics(), 'React');

package/analyzer-template/packages/ai/src/lib/astScopes/paths.ts

@@ -17,6 +17,25 @@ interface ToStringWithSegmentsOptions {
   withNestedReturnValues?: boolean;
 }
 
+/**
+ * Check if a string is a valid JavaScript identifier (can use dot notation)
+ * Valid identifiers start with a letter, underscore, or dollar sign
+ * and contain only letters, digits, underscores, and dollar signs
+ *
+ * Also allows computed property markers like *f.path* (wrapped in asterisks)
+ * which are used internally to represent dynamic property accesses
+ */
+function isValidIdentifier(name: string): boolean {
+  if (!name || name.length === 0) return false;
+  // First char: letter, underscore, or dollar sign
+  // Rest: letter, digit, underscore, or dollar sign
+  // Also allow computed property markers like *expression*
+  return (
+    /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ||
+    (name.startsWith('*') && name.endsWith('*'))
+  );
+}
+
 /**
  * A structured representation of a variable or property path
  *
@@ -335,8 +354,15 @@ export class StructuredPath {
       switch (segment.type) {
         case PathRelationship.PROPERTY:
           const propSegment = segment as PropertySegment;
-          if (result) result += '.';
-          result += propSegment.name;
+          // Use bracket notation for property names that aren't valid identifiers
+          // (e.g. names with spaces, hyphens, starting with numbers, etc.)
+          if (isValidIdentifier(propSegment.name)) {
+            if (result) result += '.';
+            result += propSegment.name;
+          } else {
+            // Use bracket notation with quoted string for non-identifier names
+            result += `['${propSegment.name}']`;
+          }
           break;
 
         case PathRelationship.ELEMENT:
@@ -389,7 +415,20 @@ export class StructuredPath {
             result += `(${argsStr})`;
           }
 
-          if (i === lastFunctionCallIndex && doRenderFunctionCallReturnValue) {
+          // Add .functionCallReturnValue if:
+          // 1. This is the last function call in the path
+          // 2. We're rendering with return values (right-hand side of equivalency)
+          // 3. The next segment is NOT a parameter (signature[n])
+          // Parameter segments represent function inputs, not outputs, so they
+          // shouldn't go through .functionCallReturnValue
+          const nextSegmentIsParameter =
+            i + 1 < segments.length &&
+            segments[i + 1].type === PathRelationship.PARAMETER;
+          if (
+            i === lastFunctionCallIndex &&
+            doRenderFunctionCallReturnValue &&
+            !nextSegmentIsParameter
+          ) {
             // Add the return value marker
             result += '.functionCallReturnValue';
           }

package/analyzer-template/packages/ai/src/lib/astScopes/patterns/forInStatementHandler.ts

@@ -22,11 +22,8 @@ export class ForInStatementHandler implements PatternHandler {
     // Process the expression being iterated over first (e.g., object)
     context.processExpression(node.expression);
 
-    // Get the path of the object being iterated
-    const expressionPath = context.getStructuralPath(node.expression);
-
-    // If the initializer is a variable declaration with an identifier, establish equivalence
-    // to indicate it's iterating over the keys of the expression
+    // If the initializer is a variable declaration with an identifier,
+    // type it as 'string' since for-in keys are always strings
     if (ts.isVariableDeclarationList(node.initializer)) {
       const declarations = node.initializer.declarations;
       if (
@@ -36,25 +33,21 @@ export class ForInStatementHandler implements PatternHandler {
       ) {
         const variableName = StructuredPath.fromBase(declarations[0].name.text);
 
-        // Add type for the key variable (string for object keys)
+        // Type the key variable as 'string' — for-in keys are always strings.
+        // Note: We intentionally do NOT equivalence the key variable to
+        // expressionPath[*key*]. The key variable is the KEY (a string),
+        // while [*key*] in the schema represents the VALUE at a dynamic key.
+        // Creating that equivalence would cause the 'string' type to propagate
+        // to the value path. The value access (e.g., obj[key]) is handled
+        // correctly by the element access handler in processExpression.
         context.addType(variableName, 'string');
-
-        if (expressionPath) {
-          // For for...in loops, the variable is equivalent to the keys of the object
-          // We represent this with a *key* suffix to indicate it's a key, not a value
-          context.addEquivalence(variableName, expressionPath.withKey('key'));
-        }
       }
     } else if (ts.isIdentifier(node.initializer)) {
       // If the initializer is directly an identifier (rare but possible)
       const variableName = StructuredPath.fromBase(node.initializer.text);
 
-      // Add type for the key variable
+      // See comment above — type as string but don't equivalence to value path
       context.addType(variableName, 'string');
-
-      if (expressionPath) {
-        context.addEquivalence(variableName, expressionPath.withKey('key'));
-      }
     } else {
       context.processExpression(node.initializer);
     }

package/analyzer-template/packages/ai/src/lib/astScopes/patterns/ifStatementHandler.ts

@@ -5,6 +5,10 @@ import {
   markConditionVariablesAsNullable,
   extractConditionalUsage,
 } from '../processExpression';
+import {
+  extractConditionalEffectsFromIfStatement,
+  findUseStateSetters,
+} from '../conditionalEffectsExtractor';
 
 /**
  * Handler for if statements
@@ -13,6 +17,7 @@ import {
  * - The condition expression
  * - The then block
  * - The else block if present
+ * - Conditional effects (setter calls inside conditionals)
  */
 export class IfStatementHandler implements PatternHandler {
   canHandle(node: ts.Node): boolean {
@@ -31,6 +36,19 @@ export class IfStatementHandler implements PatternHandler {
     // Process the condition expression first
     context.processExpression(node.expression);
 
+    // Extract conditional effects (setter calls inside this if statement)
+    const knownSetters = findUseStateSetters(context.sourceFile);
+
+    const effects = extractConditionalEffectsFromIfStatement(
+      node,
+      context,
+      knownSetters,
+    );
+
+    for (const effect of effects) {
+      context.addConditionalEffect(effect);
+    }
+
     // Process the 'then' statement block
     context.processNode(node.thenStatement);