@codeyam/codeyam-cli 0.1.0-staging.dd216e0 → 0.1.0-staging.e090cb3

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

@@ -0,0 +1,199 @@
+/**
+ * Shared utilities for detecting array-derived expressions in conditionals.
+ *
+ * These utilities detect patterns like:
+ * - arr.some(fn) → { sourcePath: 'arr', operation: 'arraySome' }
+ * - arr.every(fn) → { sourcePath: 'arr', operation: 'arrayEvery' }
+ * - arr.includes(x) → { sourcePath: 'arr', operation: 'arrayIncludes' }
+ * - arr.length → { sourcePath: 'arr', operation: 'arrayLength' }
+ *
+ * Used by both:
+ * - variableDeclarationHandler.ts (for variable assignments)
+ * - processExpression.ts (for inline conditionals)
+ */
+
+import ts from 'typescript';
+
+/** Array predicate method operations */
+export type ArrayPredicateOperation =
+  | 'arrayIncludes'
+  | 'arraySome'
+  | 'arrayEvery';
+
+/** Array length operation */
+export type ArrayLengthOperation = 'arrayLength';
+
+/** All array-derived operations */
+export type ArrayDerivedOperation =
+  | ArrayPredicateOperation
+  | ArrayLengthOperation;
+
+/** Result of detecting an array derivation pattern */
+export interface ArrayDerivationResult {
+  sourcePath: string;
+  operation: ArrayDerivedOperation;
+}
+
+/**
+ * Extracts a simple path string from an expression.
+ * Returns the path for identifiers and property access chains.
+ */
+export function getSimplePath(node: ts.Expression): string | null {
+  if (ts.isIdentifier(node)) {
+    return node.text;
+  }
+  if (ts.isPropertyAccessExpression(node)) {
+    const objectPath = getSimplePath(node.expression);
+    if (objectPath) {
+      return `${objectPath}.${node.name.text}`;
+    }
+  }
+  // Handle optional chaining: a?.b
+  if (ts.isNonNullExpression(node)) {
+    return getSimplePath(node.expression);
+  }
+  return null;
+}
+
+/**
+ * Maps array method names to derivation operation names
+ */
+function getArrayPredicateOperation(
+  methodName: string,
+): ArrayPredicateOperation | null {
+  switch (methodName) {
+    case 'includes':
+      return 'arrayIncludes';
+    case 'some':
+      return 'arraySome';
+    case 'every':
+      return 'arrayEvery';
+    default:
+      return null;
+  }
+}
+
+/**
+ * Detects if an expression is an array predicate call and extracts the array path.
+ * Patterns detected:
+ * - arr.includes(x) → { sourcePath: 'arr', operation: 'arrayIncludes' }
+ * - arr?.includes(x) → { sourcePath: 'arr', operation: 'arrayIncludes' }
+ * - arr.some(fn) → { sourcePath: 'arr', operation: 'arraySome' }
+ * - arr.every(fn) → { sourcePath: 'arr', operation: 'arrayEvery' }
+ * - Boolean(x && arr?.includes(y)) → { sourcePath: 'arr', operation: 'arrayIncludes' }
+ */
+export function detectArrayPredicatePattern(
+  expr: ts.Expression,
+): ArrayDerivationResult | null {
+  // Unwrap Boolean() calls: Boolean(x) → x
+  if (
+    ts.isCallExpression(expr) &&
+    ts.isIdentifier(expr.expression) &&
+    expr.expression.text === 'Boolean' &&
+    expr.arguments.length === 1
+  ) {
+    return detectArrayPredicatePattern(expr.arguments[0]);
+  }
+
+  // Handle logical AND: a && b - check both sides for array predicates
+  if (
+    ts.isBinaryExpression(expr) &&
+    expr.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken
+  ) {
+    // Try the right side first (more likely to have the predicate)
+    const rightResult = detectArrayPredicatePattern(expr.right);
+    if (rightResult) return rightResult;
+    // Try the left side
+    const leftResult = detectArrayPredicatePattern(expr.left);
+    if (leftResult) return leftResult;
+    return null;
+  }
+
+  // Handle parenthesized expressions
+  if (ts.isParenthesizedExpression(expr)) {
+    return detectArrayPredicatePattern(expr.expression);
+  }
+
+  if (!ts.isCallExpression(expr)) {
+    return null;
+  }
+
+  const callExpr = expr.expression;
+
+  // Handle both regular property access (arr.includes) and optional chaining (arr?.includes)
+  let objectExpr: ts.Expression | null = null;
+  let methodName: string | null = null;
+
+  if (ts.isPropertyAccessExpression(callExpr)) {
+    objectExpr = callExpr.expression;
+    methodName = callExpr.name.text;
+  } else if (
+    ts.isElementAccessExpression(callExpr) &&
+    ts.isStringLiteral(callExpr.argumentExpression)
+  ) {
+    // Handle arr["includes"]() syntax (rare but possible)
+    objectExpr = callExpr.expression;
+    methodName = callExpr.argumentExpression.text;
+  }
+
+  if (!objectExpr || !methodName) {
+    return null;
+  }
+
+  const operation = getArrayPredicateOperation(methodName);
+  if (!operation) {
+    return null;
+  }
+
+  // Get the source path for the array
+  const sourcePath = getSimplePath(objectExpr);
+  if (!sourcePath) {
+    return null;
+  }
+
+  return { sourcePath, operation };
+}
+
+/**
+ * Detects if an expression is an array.length access.
+ * Patterns detected:
+ * - arr.length → { sourcePath: 'arr', operation: 'arrayLength' }
+ * - arr?.length → { sourcePath: 'arr', operation: 'arrayLength' }
+ */
+export function detectArrayLengthPattern(
+  expr: ts.Expression,
+): ArrayDerivationResult | null {
+  // Handle property access: arr.length
+  if (ts.isPropertyAccessExpression(expr)) {
+    if (expr.name.text === 'length') {
+      const sourcePath = getSimplePath(expr.expression);
+      if (sourcePath) {
+        return { sourcePath, operation: 'arrayLength' };
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Detects any array-derived pattern (predicate methods or .length).
+ * This is the main entry point for inline conditional detection.
+ */
+export function detectArrayDerivedPattern(
+  expr: ts.Expression,
+): ArrayDerivationResult | null {
+  // Check for array predicate methods first (.some, .every, .includes)
+  const predicateResult = detectArrayPredicatePattern(expr);
+  if (predicateResult) {
+    return predicateResult;
+  }
+
+  // Check for .length access
+  const lengthResult = detectArrayLengthPattern(expr);
+  if (lengthResult) {
+    return lengthResult;
+  }
+
+  return null;
+}

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

@@ -5,7 +5,9 @@ import {
   AnalysisIssue,
   AstScopeAnalysisResult,
   CompletenessInfo,
+  CompoundConditional,
   ConditionalUsage,
+  DerivedVariableInfo,
 } from './types';
 import { PatternHandler } from './patterns/patternHandler';
 import { VariableDeclarationHandler } from './patterns/variableDeclarationHandler';
@@ -100,9 +102,20 @@ import { ThrowStatementHandler } from './patterns/throwStatementHandler';
  */
 export class ASTScopeAnalyzer {
   private structure: Record<string, string> = {};
-  private equivalentVariables: Record<string, string> = {};
+  private equivalentVariables: Record<string, string | string[]> = {};
   private environmentVariables: string[] = [];
   private conditionalUsages: Record<string, ConditionalUsage[]> = {};
+  private compoundConditionals: CompoundConditional[] = [];
+  private conditionalEffects: import('./types').ConditionalEffect[] = [];
+  private childBoundaryGatingConditions: Record<string, ConditionalUsage[]> =
+    {};
+  private jsxRenderingUsages: import('./types').JsxRenderingUsage[] = [];
+  /**
+   * Tracks derived boolean variables and their source expressions.
+   * Maps variable name to derivation info.
+   * Example: { hasAnalysis: { sourcePath: 'analysis', operation: 'notNull' } }
+   */
+  private derivedVariables: Record<string, DerivedVariableInfo> = {};
   private sourceFile: ts.SourceFile;
   private statementInfo: StatementInfo;
   private issues: AnalysisIssue[] = [];
@@ -203,6 +216,11 @@ export class ASTScopeAnalyzer {
       equivalentVariables: this.equivalentVariables,
       environmentVariables: this.environmentVariables,
       conditionalUsages: this.conditionalUsages,
+      compoundConditionals: this.compoundConditionals,
+      conditionalEffects: this.conditionalEffects,
+      derivedVariables: this.derivedVariables,
+      childBoundaryGatingConditions: this.childBoundaryGatingConditions,
+      jsxRenderingUsages: this.jsxRenderingUsages,
       isComplete:
         completeness.equivalences === 'full' &&
         completeness.structures === 'full',
@@ -217,6 +235,8 @@ export class ASTScopeAnalyzer {
       typeChecker: this.fileAnalyzer.typeChecker,
       addEquivalence: (leftSide, rightSide) =>
         this.addEquivalence(leftSide, rightSide),
+      addMultipleEquivalencies: (leftSide, rightSides) =>
+        this.addMultipleEquivalencies(leftSide, rightSides),
       addType: (path, type) => this.addType(path, type),
       addEnvironmentVariable: (variablePath) =>
         this.addEnvironmentVariable(variablePath),
@@ -245,7 +265,20 @@ export class ASTScopeAnalyzer {
         processExpression({ node, context, targetPath }),
       addConditionalUsage: (usage) => this.addConditionalUsage(usage),
       getConditionalUsages: () => this.conditionalUsages,
+      addChildBoundaryGatingCondition: (childName, condition) =>
+        this.addChildBoundaryGatingCondition(childName, condition),
+      getChildBoundaryGatingConditions: () =>
+        this.childBoundaryGatingConditions,
+      addDerivedVariable: (variableName, derivationInfo) =>
+        this.addDerivedVariable(variableName, derivationInfo),
+      addCompoundConditional: (compound) =>
+        this.addCompoundConditional(compound),
+      getCompoundConditionals: () => this.compoundConditionals,
       updateSchemaType: (path, newType) => this.updateSchemaType(path, newType),
+      addConditionalEffect: (effect) => this.addConditionalEffect(effect),
+      getConditionalEffects: () => this.conditionalEffects,
+      addJsxRenderingUsage: (usage) => this.addJsxRenderingUsage(usage),
+      getJsxRenderingUsages: () => this.jsxRenderingUsages,
     };
     return context;
   }
@@ -561,7 +594,9 @@ export class ASTScopeAnalyzer {
   }
 
   /**
-   * Adds an equivalence relationship between two variable paths
+   * Adds an equivalence relationship between two variable paths.
+   * Uses overwrite semantics - if an equivalence already exists, the new value replaces it
+   * (unless the new value is 'undefined' or 'null').
    */
   private addEquivalence(
     leftSide: StructuredPath,
@@ -576,10 +611,59 @@ export class ASTScopeAnalyzer {
     const rightSideStr = rightSide?.toRightHandSideString();
 
     if (leftSideStr && rightSideStr && leftSideStr !== rightSideStr) {
+      const existingValue = this.equivalentVariables[leftSideStr];
+      // Don't overwrite a meaningful value with 'undefined' or 'null'.
+      // This is critical for ternary conditionals like `const x = cond ? func() : undefined`
+      // or `const x = items.find(...) || null` where we want to preserve
+      // the equivalency to the more meaningful value (func()'s return value, items[]).
+      if (
+        existingValue &&
+        (rightSideStr === 'undefined' || rightSideStr === 'null')
+      ) {
+        return;
+      }
       this.equivalentVariables[leftSideStr] = rightSideStr;
     }
   }
 
+  /**
+   * Adds multiple equivalence relationships for a single variable path.
+   * Used for OR expressions like `x = a || b` where x is equivalent to both a and b.
+   * The values are stored as an array to track all possible sources.
+   */
+  private addMultipleEquivalencies(
+    leftSide: StructuredPath,
+    rightSides: StructuredPath[],
+  ): void {
+    if (leftSide?.isLiteral()) {
+      return;
+    }
+
+    const leftSideStr = leftSide?.toLeftHandSideString();
+    if (!leftSideStr) return;
+
+    // Filter out invalid paths and convert to strings
+    const validRightSides = rightSides
+      .map((r) => r?.toRightHandSideString())
+      .filter((r): r is string => !!r && r !== leftSideStr);
+
+    // Remove duplicates while preserving order
+    const uniqueRightSides = [...new Set(validRightSides)];
+
+    // Filter out 'undefined' and 'null' unless they're the only values
+    const meaningfulValues = uniqueRightSides.filter(
+      (v) => v !== 'undefined' && v !== 'null',
+    );
+    const finalValues =
+      meaningfulValues.length > 0 ? meaningfulValues : uniqueRightSides;
+
+    if (finalValues.length === 0) return;
+
+    // Store as single value if only one, otherwise as array
+    this.equivalentVariables[leftSideStr] =
+      finalValues.length === 1 ? finalValues[0] : finalValues;
+  }
+
   /**
    * Adds a type for a variable path
    */
@@ -607,11 +691,39 @@ export class ASTScopeAnalyzer {
     }
   }
 
+  /**
+   * Record a derived variable and its source expression.
+   * Called when we see patterns like:
+   * - const hasAnalysis = analysis !== null
+   * - const isLoading = status === 'loading'
+   * - const isBusy = isRunning || isQueued
+   */
+  private addDerivedVariable(
+    variableName: string,
+    derivationInfo: DerivedVariableInfo,
+  ): void {
+    this.derivedVariables[variableName] = derivationInfo;
+  }
+
+  /**
+   * Get derivation info for a variable if it was derived from another expression.
+   */
+  private getDerivedVariableInfo(
+    variableName: string,
+  ): DerivedVariableInfo | undefined {
+    return this.derivedVariables[variableName];
+  }
+
   /**
    * Add a conditional usage for key attribute detection
-   * Groups usages by path for easy lookup
+   * Groups usages by path for easy lookup.
+   * Also enriches the usage with derivation info if the variable is derived.
    */
   private addConditionalUsage(usage: ConditionalUsage): void {
+    // Note: Derivation info enrichment now happens in analyzeScope.ts after all
+    // statements are processed, so derived variables from earlier statements can
+    // be used to enrich usages from later statements.
+
     if (!this.conditionalUsages[usage.path]) {
       this.conditionalUsages[usage.path] = [];
     }
@@ -628,6 +740,73 @@ export class ASTScopeAnalyzer {
     }
   }
 
+  /**
+   * Add a gating condition for a child component.
+   * Called when we see patterns like: {hasAnalysis && <ChildComponent />}
+   * Groups conditions by child component name.
+   */
+  private addChildBoundaryGatingCondition(
+    childComponentName: string,
+    gatingCondition: ConditionalUsage,
+  ): void {
+    if (!this.childBoundaryGatingConditions[childComponentName]) {
+      this.childBoundaryGatingConditions[childComponentName] = [];
+    }
+    // Avoid duplicates with same path and conditionType
+    const exists = this.childBoundaryGatingConditions[childComponentName].some(
+      (existing) =>
+        existing.path === gatingCondition.path &&
+        existing.conditionType === gatingCondition.conditionType &&
+        existing.isNegated === gatingCondition.isNegated,
+    );
+    if (!exists) {
+      this.childBoundaryGatingConditions[childComponentName].push(
+        gatingCondition,
+      );
+    }
+  }
+
+  /**
+   * Add a compound conditional for key attribute dependency detection
+   */
+  private addCompoundConditional(compound: CompoundConditional): void {
+    // Avoid duplicates by expression and location (chainId is generated each time)
+    const exists = this.compoundConditionals.some(
+      (existing) =>
+        existing.expression === compound.expression &&
+        existing.sourceLocation.lineNumber ===
+          compound.sourceLocation.lineNumber,
+    );
+    if (!exists) {
+      this.compoundConditionals.push(compound);
+    }
+  }
+
+  /**
+   * Add a conditional effect (setter call inside a conditional)
+   */
+  private addConditionalEffect(
+    effect: import('./types').ConditionalEffect,
+  ): void {
+    this.conditionalEffects.push(effect);
+  }
+
+  /**
+   * Add a JSX rendering usage (array.map() or text interpolation)
+   * Deduplicates by path and rendering type
+   */
+  private addJsxRenderingUsage(
+    usage: import('./types').JsxRenderingUsage,
+  ): void {
+    // Deduplicate: don't add if we already have the same path + renderingType
+    const exists = this.jsxRenderingUsages.some(
+      (u) => u.path === usage.path && u.renderingType === usage.renderingType,
+    );
+    if (!exists) {
+      this.jsxRenderingUsages.push(usage);
+    }
+  }
+
   /**
    * Updates the schema type for a path, typically used when switch statements
    * reveal the valid values for a parameter (creating a union type like "'a' | 'b' | 'c'")
@@ -648,22 +827,38 @@ export class ASTScopeAnalyzer {
     // Update the type for the given path
     this.structure[pathStr] = newType;
 
-    // Also update the type for any equivalent path
+    // Also update the type for any equivalent path(s)
     // e.g., if "state" -> "signature[0]", update "signature[0]" as well
-    const equivalentPath = this.equivalentVariables[pathStr];
-    if (equivalentPath) {
-      this.structure[equivalentPath] = newType;
+    const rawEquivalentPath = this.equivalentVariables[pathStr];
+    const equivalentPaths = Array.isArray(rawEquivalentPath)
+      ? rawEquivalentPath
+      : rawEquivalentPath
+        ? [rawEquivalentPath]
+        : [];
+    for (const equivalentPath of equivalentPaths) {
+      if (typeof equivalentPath === 'string') {
+        this.structure[equivalentPath] = newType;
+      }
     }
 
     // For property paths like "data.status", check if the base has an equivalence
     // e.g., if "data" -> "signature[0]", transform "data.status" to "signature[0].status"
-    for (const [varPath, equivalence] of Object.entries(
+    for (const [varPath, rawEquivalence] of Object.entries(
       this.equivalentVariables,
     )) {
       if (pathStr.startsWith(varPath + '.')) {
+        const equivalences = Array.isArray(rawEquivalence)
+          ? rawEquivalence
+          : rawEquivalence
+            ? [rawEquivalence]
+            : [];
         const suffix = pathStr.slice(varPath.length);
-        const transformedPath = equivalence + suffix;
-        this.structure[transformedPath] = newType;
+        for (const equivalence of equivalences) {
+          if (typeof equivalence === 'string') {
+            const transformedPath = equivalence + suffix;
+            this.structure[transformedPath] = newType;
+          }
+        }
       }
     }
   }