@codeyam/codeyam-cli 0.1.0-staging.d0ad4ae → 0.1.0-staging.d3e886e

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

@@ -71,6 +71,34 @@ export function isComparisonOperator(kind: ts.SyntaxKind): boolean {
   );
 }
 
+/**
+ * Returns the string representation of a comparison operator token.
+ */
+export function getComparisonOperatorString(
+  kind: ts.SyntaxKind,
+): string | undefined {
+  switch (kind) {
+    case ts.SyntaxKind.EqualsEqualsToken:
+      return '==';
+    case ts.SyntaxKind.EqualsEqualsEqualsToken:
+      return '===';
+    case ts.SyntaxKind.ExclamationEqualsToken:
+      return '!=';
+    case ts.SyntaxKind.ExclamationEqualsEqualsToken:
+      return '!==';
+    case ts.SyntaxKind.LessThanToken:
+      return '<';
+    case ts.SyntaxKind.LessThanEqualsToken:
+      return '<=';
+    case ts.SyntaxKind.GreaterThanToken:
+      return '>';
+    case ts.SyntaxKind.GreaterThanEqualsToken:
+      return '>=';
+    default:
+      return undefined;
+  }
+}
+
 /**
  * Checks if an operator is an arithmetic operator
  */

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

@@ -142,15 +142,154 @@ export interface VariablePath {
   segments: PathSegment[];
 }
 
+/**
+ * Represents the effect of a setter call within a conditional block.
+ * This tracks what state changes occur when specific conditions are met.
+ *
+ * Example: if (data.success) { setShowModal(true); }
+ * - condition: data.success = truthy
+ * - effect: setShowModal called with true
+ */
+export interface ConditionalEffect {
+  /**
+   * Single condition that controls this effect.
+   * Use this for simple if statements with a single condition.
+   */
+  condition?: {
+    /** The path being checked (e.g., "data.success") */
+    path: string;
+    /** Type of condition check */
+    conditionType: 'truthiness' | 'comparison' | 'switch';
+    /** Values being compared against (for comparison/switch) */
+    comparedValues?: string[];
+    /** The value required for this effect to occur */
+    requiredValue: string | boolean;
+  };
+
+  /**
+   * Multiple conditions that all must be true for this effect.
+   * Use this for compound conditions (a && b && c).
+   */
+  conditions?: Array<{
+    /** The path being checked */
+    path: string;
+    /** Type of condition check */
+    conditionType: 'truthiness' | 'comparison' | 'switch';
+    /** Values being compared against */
+    comparedValues?: string[];
+    /** The value required for this condition to be true */
+    requiredValue: string | boolean;
+  }>;
+
+  /**
+   * The effect that occurs when the condition(s) are met.
+   */
+  effect: {
+    /** Type of effect - currently only 'setter' for useState setters */
+    type: 'setter';
+    /** The state variable name (e.g., "showModal" from [showModal, setShowModal]) */
+    stateVariable: string;
+    /** The setter function name (e.g., "setShowModal") */
+    setterName: string;
+    /** The value being set (literal or expression text) */
+    value: string;
+    /** The type of value being set */
+    valueType: 'string' | 'number' | 'boolean' | 'null' | 'dynamic';
+  };
+
+  /**
+   * Source location for this conditional effect
+   */
+  sourceLocation?: {
+    lineNumber: number;
+    column: number;
+    codeSnippet: string;
+  };
+}
+
 /**
  * Results of AST-based scope analysis
  */
+
+/**
+ * Operation types for derived variables.
+ * - notNull/isNull: null checks (x !== null, x === null)
+ * - equals/notEquals: value comparisons (x === 'value', x !== 'value')
+ * - or/and: logical combinations (a || b, a && b)
+ * - arrayIncludes/arraySome/arrayEvery: array predicate methods
+ * - arrayLength: array.length property access
+ */
+export type DerivedVariableOperation =
+  | 'notNull'
+  | 'isNull'
+  | 'equals'
+  | 'notEquals'
+  | 'or'
+  | 'and'
+  | 'arrayIncludes'
+  | 'arraySome'
+  | 'arrayEvery'
+  | 'arrayLength';
+
+/**
+ * Information about how a variable was derived from other variables.
+ * Used to trace derived boolean variables back to their data sources.
+ */
+export interface DerivedVariableInfo {
+  /** For single-source derivations (notNull, equals, array predicates, etc.) */
+  sourcePath?: string;
+  /** For multi-source derivations (or, and) */
+  sourcePaths?: string[];
+  /** The operation that derived this variable */
+  operation: DerivedVariableOperation;
+  /** For comparison operations, the value being compared to */
+  comparedValue?: string;
+}
+
+/**
+ * Represents a JSX rendering usage where arrays or strings are rendered directly.
+ * Used to generate execution flows for array sizes and text lengths
+ * even without explicit conditionals.
+ *
+ * Examples:
+ * - `{items.map(i => <Item {...i} />)}` → array-map usage for 'items'
+ * - `{user.name}` → text-interpolation usage for 'user.name'
+ */
+export interface JsxRenderingUsage {
+  /**
+   * The path to the rendered value (e.g., "items", "data.users", "user.name")
+   */
+  path: string;
+
+  /**
+   * Type of rendering:
+   * - 'array-map': Array rendered via .map() method
+   * - 'text-interpolation': String rendered directly in JSX
+   */
+  renderingType: 'array-map' | 'text-interpolation';
+
+  /**
+   * The detected type of the value being rendered
+   */
+  valueType?: 'array' | 'string' | 'unknown';
+
+  /**
+   * Source location information
+   */
+  sourceLocation?: {
+    lineNumber: number;
+    column: number;
+    codeSnippet: string;
+  };
+}
+
 export interface AstScopeAnalysisResult {
   // Variable structure map (variable path -> type)
   structure: Record<string, string>;
 
-  // Variable equivalence map (variable path -> equivalent variable path)
-  equivalentVariables: Record<string, string>;
+  // Variable equivalence map (variable path -> equivalent variable path(s))
+  // Supports multiple equivalencies per key for OR expressions (e.g., x = a || b)
+  equivalentVariables: Record<string, string | string[]>;
 
   // Environment variables accessed in this scope
   environmentVariables: string[];
@@ -162,6 +301,24 @@ export interface AstScopeAnalysisResult {
   // Compound conditionals grouped by chain (all conditions must be true together)
   compoundConditionals?: CompoundConditional[];
 
+  // Conditional effects - tracks what setter calls happen inside conditionals
+  // This allows us to determine what data conditions must be true for different state changes
+  conditionalEffects: ConditionalEffect[];
+
+  // Derived variables - variables computed from boolean expressions
+  // Maps variable name to derivation info (e.g., hasAnalysis -> { sourcePath: 'analysis', operation: 'notNull' })
+  derivedVariables?: Record<string, DerivedVariableInfo>;
+
+  // Child boundary gating conditions - tracks which conditions must be true for a child component to render
+  // Maps child component name to array of conditional usages that gate its rendering
+  // Example: {hasAnalysis && <ScenarioViewer />} → { ScenarioViewer: [{ path: 'hasAnalysis', ... }] }
+  childBoundaryGatingConditions?: Record<string, ConditionalUsage[]>;
+
+  // JSX rendering usages - tracks arrays rendered via .map() and strings interpolated in JSX
+  // Used to generate execution flows for array sizes and text lengths without explicit conditionals
+  // Example: {items.map(i => <Item {...i} />)} → array-map usage for 'items'
+  jsxRenderingUsages?: JsxRenderingUsage[];
+
   // Whether the analysis is complete enough to skip LLM calls
   isComplete: boolean;
 
@@ -192,8 +349,9 @@ export interface ConditionalUsage {
 
   /**
    * Where this conditional usage occurs
+   * 'unconditional' is used for children that are always rendered but receive data props
    */
-  location: 'if' | 'ternary' | 'logical-and' | 'switch';
+  location: 'if' | 'ternary' | 'logical-and' | 'switch' | 'unconditional';
 
   /**
    * Source location information for this conditional usage
@@ -217,6 +375,45 @@ export interface ConditionalUsage {
   chainExpression?: string;
   /** Whether this condition is negated (e.g., !foo) */
   isNegated?: boolean;
+  /**
+   * Whether this conditional controls JSX rendering.
+   * True when the conditional appears in a JSX expression like {cond && <Component />}
+   * or {cond ? <A /> : <B />}. Used to identify high-impact execution flows.
+   */
+  controlsJsxRendering?: boolean;
+
+  /**
+   * Information about how this variable was derived from other variables.
+   * Used to trace derived boolean variables back to their data sources.
+   *
+   * Examples:
+   * - `const hasAnalysis = analysis !== null` → { sourcePath: 'analysis', operation: 'notNull' }
+   * - `const isLoading = status === 'loading'` → { sourcePath: 'status', operation: 'equals', comparedValue: 'loading' }
+   * - `const isBusy = isRunning || isQueued` → { operation: 'or', sourcePaths: ['isRunning', 'isQueued'] }
+   */
+  derivedFrom?: {
+    /** For single-source derivations (notNull, equals, array predicates, etc.) */
+    sourcePath?: string;
+    /** For multi-source derivations (or, and) */
+    sourcePaths?: string[];
+    /** The operation that derived this variable */
+    operation: DerivedVariableOperation;
+    /** For comparison operations, the value being compared to */
+    comparedValue?: string;
+  };
+
+  /**
+   * The full original expression as a semantic constraint for LLM reasoning.
+   * Used when the path contains complex operations (filter, map, etc.) that
+   * can't be simply resolved to a mock value.
+   *
+   * Examples:
+   * - `scenarios.filter(s => s.active).length > 1`
+   * - `users.some(u => u.role === 'admin' && u.active)`
+   *
+   * The LLM can interpret this constraint to generate appropriate mock data.
+   */
+  constraintExpression?: string;
 }
 
 /**
@@ -236,15 +433,35 @@ export interface CompoundConditional {
     isNegated: boolean;
     /** Required value for this condition to be true */
     requiredValue?: string | boolean;
+    /**
+     * The comparison operator used (e.g., '>', '<', '>=', '<=', '===', '!==').
+     * Preserves the original operator so flow generation can distinguish
+     * `length > 0` from `length === 0`.
+     */
+    comparisonOperator?: string;
+    /**
+     * When conditions are part of an OR expression within an && chain,
+     * they share the same orGroupId. Conditions with the same orGroupId
+     * are alternatives - only ONE needs to be satisfied.
+     * Example: `A && (B || C)` creates conditions where B and C share an orGroupId.
+     * This allows flow generation to expand into separate flows: A&&B and A&&C.
+     */
+    orGroupId?: string;
   }[];
   /** Where this compound conditional occurs */
-  location: 'if' | 'ternary' | 'logical-and' | 'switch';
+  location: 'if' | 'ternary' | 'logical-and' | 'switch' | 'unconditional';
   /** Source location for the entire compound expression */
   sourceLocation: {
     lineNumber: number;
     column: number;
     codeSnippet: string;
   };
+  /**
+   * Whether this compound conditional controls JSX rendering.
+   * True when the conditional appears in a JSX expression like {a && b && <Component />}
+   * Used to identify high-impact execution flows.
+   */
+  controlsJsxRendering?: boolean;
 }
 
 /**
@@ -300,6 +517,13 @@ export interface AnalysisContext {
   // Add an equivalence relationship between two variable paths
   addEquivalence(leftSide: StructuredPath, rightSide: StructuredPath): void;
 
+  // Add 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.
+  addMultipleEquivalencies(
+    leftSide: StructuredPath,
+    rightSides: StructuredPath[],
+  ): void;
+
   // Add a type for a variable path
   addType(path: StructuredPath, type: string): void;
 
@@ -346,8 +570,8 @@ export interface AnalysisContext {
   // Get the built-up structure
   getStructure(): Record<string, string>;
 
-  // Get the built-up equivalence map
-  getEquivalentVariables(): Record<string, string>;
+  // Get the built-up equivalence map (supports multiple values for OR expressions)
+  getEquivalentVariables(): Record<string, string | string[]>;
 
   // Utilties for child boundaries (need to be skipped while capturing equivalencies)
   getChildBoundary(
@@ -372,6 +596,28 @@ export interface AnalysisContext {
   // Get all conditional usages
   getConditionalUsages(): Record<string, ConditionalUsage[]>;
 
+  // Add a gating condition for a child component
+  // Called when we see patterns like: {hasAnalysis && <ChildComponent />}
+  addChildBoundaryGatingCondition(
+    childComponentName: string,
+    gatingCondition: ConditionalUsage,
+  ): void;
+
+  // Get all child boundary gating conditions
+  getChildBoundaryGatingConditions(): Record<string, ConditionalUsage[]>;
+
+  // Record a derived variable and its source expression
+  // Called when we see patterns like: const hasAnalysis = analysis !== null
+  addDerivedVariable(
+    variableName: string,
+    derivationInfo: {
+      sourcePath?: string;
+      sourcePaths?: string[];
+      operation: DerivedVariableOperation;
+      comparedValue?: string;
+    },
+  ): void;
+
   // Add a compound conditional for key attribute dependency detection
   addCompoundConditional(compound: CompoundConditional): void;
 
@@ -381,4 +627,17 @@ export interface AnalysisContext {
   // Update a schema type, typically used when switch statements reveal
   // the valid values for a parameter (creating a union type)
   updateSchemaType(path: string | StructuredPath, newType: string): void;
+
+  // Add a conditional effect (setter call inside a conditional)
+  addConditionalEffect(effect: ConditionalEffect): void;
+
+  // Get all conditional effects
+  getConditionalEffects(): ConditionalEffect[];
+
+  // Add a JSX rendering usage (array.map() or text interpolation)
+  // Called when we see patterns like: {items.map(i => <Item />)} or {user.name}
+  addJsxRenderingUsage(usage: JsxRenderingUsage): void;
+
+  // Get all JSX rendering usages
+  getJsxRenderingUsages(): JsxRenderingUsage[];
 }