@codeyam/codeyam-cli 0.1.0-staging.1669d45 → 0.1.0-staging.1a2737b

package/analyzer-template/packages/ai/src/lib/generateEntityScenarios.ts

@@ -1,6 +1,7 @@
 import completionCall from './completionCall';
 import { saveLlmCall } from '~codeyam/aws/dynamodb';
 import generateEntityScenariosGenerator from './promptGenerators/generateEntityScenariosGenerator';
+import { getFlowsForScenarioGeneration } from './generateExecutionFlows';
 
 import {
   Analysis,
@@ -13,6 +14,13 @@ import { awsLog } from '~codeyam/utils';
 import { sanitizePlaywrightInstructions } from './validatePlaywrightInstructions';
 import { AI, DEFAULT_LARGER_MODEL, parseJsonSafe } from '~codeyam/ai';
 
+/**
+ * Maximum number of execution flows to send to the LLM for scenario generation.
+ * When there are more flows than this threshold, we filter to the top N
+ * highest priority flows to avoid overwhelming the LLM and wasting tokens.
+ */
+const MAX_FLOWS_FOR_SCENARIO_GENERATION = 30;
+
 export interface ScenarioResult {
   name: string;
   testName: string;
@@ -75,9 +83,26 @@ export default async function generateEntityScenarios({
     };
   }
 
+  // Filter execution flows to top N highest priority when there are many flows
+  // This prevents overwhelming the LLM and wasting tokens on low-priority flows
+  let filteredFlows = executionFlows;
+  if (
+    executionFlows &&
+    executionFlows.length > MAX_FLOWS_FOR_SCENARIO_GENERATION
+  ) {
+    filteredFlows = getFlowsForScenarioGeneration(executionFlows, {
+      maxFlows: MAX_FLOWS_FOR_SCENARIO_GENERATION,
+      ensureGroupDiversity: true,
+    }) as ExecutionFlow[];
+
+    console.log(
+      `CodeYam: Filtered ${executionFlows.length} flows to ${filteredFlows.length} for scenario generation`,
+    );
+  }
+
   const prompt = generateEntityScenariosGenerator({
     entity,
-    executionFlows,
+    executionFlows: filteredFlows,
     error,
   });
 
@@ -151,11 +176,15 @@ export default async function generateEntityScenarios({
     return { scenarios: [], llmCall };
   }
 
-  const scenarios = (
-    result[
-      `${error ? 'errorD' : 'd'}ataScenarios`
-    ] as unknown as ScenarioResult[]
-  ).map(
+  const dataScenarios = result[`${error ? 'errorD' : 'd'}ataScenarios`];
+
+  // Gracefully handle missing dataScenarios (e.g., when LLM returns unexpected format
+  // or when test fixtures don't include the expected key)
+  if (!Array.isArray(dataScenarios)) {
+    return { scenarios: [], llmCall };
+  }
+
+  const scenarios = (dataScenarios as unknown as ScenarioResult[]).map(
     (scenarioInfo) =>
       ({
         projectId: entity.projectId,

package/analyzer-template/packages/ai/src/lib/generateExecutionFlows.ts

@@ -5,6 +5,7 @@
  * instead of LLM calls. Flows are derived from:
  * 1. conditionalUsages - variables used in if/ternary/&&/switch
  * 2. conditionalEffects - setter calls inside conditionals
+ * 3. jsxRenderingUsages - arrays rendered via .map() and strings interpolated in JSX
  *
  * Only paths that resolve to controllable data sources produce flows,
  * eliminating the problem of invalid paths like useState variables.
@@ -20,13 +21,40 @@ import { awsLog } from '~codeyam/utils';
 import { gatherAttributesMap } from './promptGenerators/gatherAttributesMap';
 import { fillInDirectSchemaGapsAndUnknowns } from './dataStructure/helpers/fillInSchemaGapsAndUnknowns';
 import { clearAttributesFromMapping } from './dataStructure/helpers/cleanNonObjectFunctions';
-import type { CompoundConditional, ConditionalUsage } from '~codeyam/types';
+import type { CompoundConditional } from '~codeyam/types';
 import { LlmCall } from '~codeyam/types';
 import generateExecutionFlowsFromConditionalEffects from './generateExecutionFlowsFromConditionalEffects';
 import generateExecutionFlowsFromConditionals, {
   ChildComponentConditionalData,
 } from './generateExecutionFlowsFromConditionals';
+import generateExecutionFlowsFromJsxUsages from './generateExecutionFlowsFromJsxUsages';
+import resolvePathToControllable from './resolvePathToControllable';
 import { AI } from '~codeyam/ai';
+import type { JsxRenderingUsage, ConditionalUsage } from './astScopes/types';
+
+/**
+ * Patterns that indicate a child component is a modal/overlay/blocking element.
+ * Same patterns used in generateExecutionFlowsFromConditionalEffects.ts for
+ * state variable names — here applied to child component names.
+ */
+const BLOCKING_CHILD_PATTERNS = [
+  /modal/i,
+  /overlay/i,
+  /dialog/i,
+  /popup/i,
+  /drawer/i,
+  /sheet/i,
+  /lightbox/i,
+  /backdrop/i,
+];
+
+/**
+ * Check if a child component name suggests it's a blocking/modal element.
+ * Exported for testing.
+ */
+export function isBlockingChildComponent(componentName: string): boolean {
+  return BLOCKING_CHILD_PATTERNS.some((pattern) => pattern.test(componentName));
+}
 
 interface GenerateExecutionFlowsArgs {
   entity: Pick<Entity, 'sha' | 'name' | 'filePath' | 'code' | 'metadata'>;
@@ -55,6 +83,7 @@ export default function generateExecutionFlows({
   });
 
   const isolatedDataStructure = entity.metadata?.isolatedDataStructure;
+
   const equivalentSignatureVariables =
     isolatedDataStructure?.equivalentSignatureVariables ?? {};
   const { attributesMap, associationMap } = gatherAttributesMap(
@@ -92,13 +121,27 @@ export default function generateExecutionFlows({
   });
 
   // Build fullToShortPathMap from associationMap
-  // associationMap maps full paths → short paths (e.g., "useFetcher<...>().functionCallReturnValue.state" → "state")
-  // fullToShortPathMap is the same mapping (we just use associationMap directly)
+  // When reverse=true (which is what we pass), associationMap maps short→full
+  // (e.g., "state" → "useFetcher<...>().functionCallReturnValue.state")
+  // We need full→short for path resolution lookups
   const fullToShortPathMap: Record<string, string> = {};
-  for (const [fullPath, shortPath] of Object.entries(associationMap)) {
+  for (const [shortPath, fullPath] of Object.entries(associationMap)) {
     fullToShortPathMap[fullPath] = shortPath;
   }
 
+  console.log(
+    `[generateExecutionFlows] ${entity.name}: attributesMap has ${Object.keys(resolvedAttributesMap).length} keys, fullToShortPathMap has ${Object.keys(fullToShortPathMap).length} entries`,
+  );
+  console.log(
+    `[generateExecutionFlows] ${entity.name}: attributesMap keys: [${Object.keys(resolvedAttributesMap).join(', ')}]`,
+  );
+  console.log(
+    `[generateExecutionFlows] ${entity.name}: fullToShortPathMap: ${JSON.stringify(fullToShortPathMap)}`,
+  );
+  console.log(
+    `[generateExecutionFlows] ${entity.name}: equivalentSignatureVariables: ${JSON.stringify(equivalentSignatureVariables)}`,
+  );
+
   // Get pre-computed conditional data from metadata
   const conditionalUsages: Record<string, ConditionalUsage[]> =
     entity.metadata?.isolatedDataStructure?.conditionalUsages ?? {};
@@ -106,6 +149,11 @@ export default function generateExecutionFlows({
     entity.metadata?.isolatedDataStructure?.compoundConditionals ?? [];
   const conditionalEffects: ConditionalEffect[] =
     entity.metadata?.isolatedDataStructure?.conditionalEffects ?? [];
+  // Get derivedVariables for multi-level derivation tracing
+  // This allows tracing through intermediate derived variables that aren't directly
+  // used in conditionals (e.g., isInCurrentRun that feeds into isAnalyzing)
+  const derivedVariables =
+    entity.metadata?.isolatedDataStructure?.derivedVariables;
 
   // Build child component data for merging child flows into parent
   // This requires:
@@ -132,11 +180,32 @@ export default function generateExecutionFlows({
             childIsolated.equivalentSignatureVariables ?? {},
           compoundConditionals: childIsolated.compoundConditionals ?? [],
           gatingConditions,
+          jsxRenderingUsages: childIsolated.jsxRenderingUsages ?? [],
         };
       }
     }
   }
 
+  console.log(
+    `[generateExecutionFlows] ${entity.name}: conditionalUsages keys: [${Object.keys(conditionalUsages).join(', ')}]`,
+  );
+  console.log(
+    `[generateExecutionFlows] ${entity.name}: conditionalUsages sourceDataPaths: ${JSON.stringify(
+      Object.fromEntries(
+        Object.entries(conditionalUsages).map(([k, v]) => [
+          k,
+          (v as any[]).map((u: any) => u.sourceDataPath ?? '(none)'),
+        ]),
+      ),
+    )}`,
+  );
+  console.log(
+    `[generateExecutionFlows] ${entity.name}: compoundConditionals count: ${compoundConditionals.length}`,
+  );
+  console.log(
+    `[generateExecutionFlows] ${entity.name}: sourceEquivalencies keys count: ${Object.keys(mergedDataStructure.sourceEquivalencies ?? {}).length}`,
+  );
+
   const conditionalsBasedFlows = generateExecutionFlowsFromConditionals({
     conditionalUsages,
     compoundConditionals,
@@ -147,6 +216,8 @@ export default function generateExecutionFlows({
       Object.keys(childComponentData).length > 0
         ? childComponentData
         : undefined,
+    derivedVariables,
+    sourceEquivalencies: mergedDataStructure.sourceEquivalencies,
   });
 
   console.log(
@@ -169,8 +240,22 @@ export default function generateExecutionFlows({
     `CodeYam: Generated ${effectsBasedFlows.length} flows from conditional effects`,
   );
 
+  // Generate flows from JSX rendering usages (array.map, text interpolation)
+  const jsxRenderingUsages: JsxRenderingUsage[] =
+    entity.metadata?.isolatedDataStructure?.jsxRenderingUsages ?? [];
+
+  const jsxBasedFlows = generateExecutionFlowsFromJsxUsages({
+    jsxRenderingUsages,
+    attributesMap: resolvedAttributesMap,
+    equivalentSignatureVariables,
+    fullToShortPathMap,
+    structure: isolatedDataStructure?.structure ?? {},
+  });
+
   // Merge all flows, deduplicating by ID
   // Effects-based flows take precedence as they have precise data source paths
+  // Conditionals-based flows second
+  // JSX-based flows last (lower priority as they're variation flows)
   const allFlows: ExecutionFlow[] = [];
   const seenIds = new Set<string>();
 
@@ -190,12 +275,436 @@ export default function generateExecutionFlows({
     }
   }
 
-  console.log(
-    `CodeYam: Total execution flows for ${entity.name}: ${allFlows.length}`,
+  // Add JSX-based flows (lowest priority - variation flows)
+  for (const flow of jsxBasedFlows) {
+    if (!seenIds.has(flow.id)) {
+      seenIds.add(flow.id);
+      allFlows.push(flow);
+    }
+  }
+
+  // Build a map of gating paths → child components they gate
+  // This allows us to identify which flows control child component rendering
+  const gatingPathToChildren = buildGatingPathToChildrenMap(
+    childBoundaryGatingConditions,
+    equivalentSignatureVariables,
+    resolvedAttributesMap,
+    fullToShortPathMap,
   );
 
+  // Calculate priority and childComponentsControlled for each flow
+  for (const flow of allFlows) {
+    calculateFlowPriority(flow, gatingPathToChildren);
+  }
+
+  // Assign exclusiveGroup for truthy/falsy flow pairs that control child components.
+  // When the same gating path produces both a truthy flow (show component) and a
+  // falsy flow (hide component), they are mutually exclusive and should be grouped.
+  assignExclusiveGroupsForGatingPairs(allFlows);
+
+  // Sort flows by priority (highest first)
+  allFlows.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+
   return {
     executionFlows: allFlows,
     llmCall: null as LlmCall | null, // No LLM calls in static analysis mode
   };
 }
+
+/**
+ * Build a map of gating paths to the child components they gate.
+ * This is used to identify which flows control child component rendering.
+ */
+function buildGatingPathToChildrenMap(
+  childBoundaryGatingConditions: Record<string, ConditionalUsage[]>,
+  equivalentSignatureVariables: Record<string, string | string[]>,
+  attributesMap: Record<string, string>,
+  fullToShortPathMap: Record<string, string>,
+): Map<string, string[]> {
+  const gatingPathToChildren = new Map<string, string[]>();
+
+  for (const [childName, gatingConditions] of Object.entries(
+    childBoundaryGatingConditions,
+  )) {
+    for (const condition of gatingConditions) {
+      // Get the path that gates this child
+      let gatingPath = condition.path;
+
+      // If there's a derivedFrom sourcePath, use that
+      if (condition.derivedFrom?.sourcePath) {
+        gatingPath = condition.derivedFrom.sourcePath;
+      }
+
+      // Try to resolve to a controllable path
+      const resolution = resolvePathToControllable(
+        gatingPath,
+        attributesMap,
+        equivalentSignatureVariables,
+        fullToShortPathMap,
+      );
+
+      // Get the equivalent, handling array case (use first element if array)
+      const equiv = equivalentSignatureVariables[gatingPath];
+      const equivPath = Array.isArray(equiv) ? equiv[0] : equiv;
+      const finalPath =
+        resolution.isControllable && resolution.resolvedPath
+          ? resolution.resolvedPath
+          : (equivPath ?? gatingPath);
+
+      // Add this child to the list of children gated by this path
+      const existing = gatingPathToChildren.get(finalPath) ?? [];
+      if (!existing.includes(childName)) {
+        existing.push(childName);
+        gatingPathToChildren.set(finalPath, existing);
+      }
+
+      // Also handle comparison conditions like "activeTab === 'scenarios'"
+      const comparisonMatch = gatingPath.match(
+        /^([a-zA-Z_][a-zA-Z0-9_]*)\s*(===?|!==?)\s*['"]?([^'"]+)['"]?$/,
+      );
+      if (comparisonMatch) {
+        const [, varName] = comparisonMatch;
+        const varResolution = resolvePathToControllable(
+          varName,
+          attributesMap,
+          equivalentSignatureVariables,
+          fullToShortPathMap,
+        );
+        // Get the equivalent, handling array case (use first element if array)
+        const varEquiv = equivalentSignatureVariables[varName];
+        const varEquivPath = Array.isArray(varEquiv) ? varEquiv[0] : varEquiv;
+        const resolvedVarPath =
+          varResolution.isControllable && varResolution.resolvedPath
+            ? varResolution.resolvedPath
+            : (varEquivPath ?? varName);
+
+        const varExisting = gatingPathToChildren.get(resolvedVarPath) ?? [];
+        if (!varExisting.includes(childName)) {
+          varExisting.push(childName);
+          gatingPathToChildren.set(resolvedVarPath, varExisting);
+        }
+      }
+    }
+  }
+
+  return gatingPathToChildren;
+}
+
+/**
+ * Assign exclusiveGroup for truthy/falsy flow pairs that control child components.
+ *
+ * When the same attribute path produces both a truthy and falsy flow (e.g.,
+ * {diffView && <DiffModal/>}), they are mutually exclusive — only one can be
+ * active at a time. Grouping them ensures the scenario generator treats them
+ * as alternative states rather than combining them.
+ */
+function assignExclusiveGroupsForGatingPairs(flows: ExecutionFlow[]): void {
+  // Build a map: attributePath -> flows with truthy or falsy comparison for that path
+  const pathToFlows = new Map<
+    string,
+    { truthy: ExecutionFlow[]; falsy: ExecutionFlow[] }
+  >();
+
+  for (const flow of flows) {
+    // Only consider flows that control child components
+    if (!flow.childComponentsControlled?.length) continue;
+
+    for (const rv of flow.requiredValues) {
+      if (rv.comparison === 'truthy' || rv.comparison === 'falsy') {
+        if (!pathToFlows.has(rv.attributePath)) {
+          pathToFlows.set(rv.attributePath, { truthy: [], falsy: [] });
+        }
+        pathToFlows.get(rv.attributePath)![rv.comparison].push(flow);
+      }
+    }
+  }
+
+  // Also check falsy flows that DON'T have childComponentsControlled —
+  // they still pair with truthy flows that do
+  for (const flow of flows) {
+    if (flow.childComponentsControlled?.length) continue; // Already processed
+
+    for (const rv of flow.requiredValues) {
+      if (rv.comparison === 'falsy' && pathToFlows.has(rv.attributePath)) {
+        pathToFlows.get(rv.attributePath)!.falsy.push(flow);
+      }
+    }
+  }
+
+  // Assign exclusiveGroup where both truthy and falsy flows exist
+  for (const [attributePath, { truthy, falsy }] of pathToFlows) {
+    if (truthy.length > 0 && falsy.length > 0) {
+      const groupName = `gating:${attributePath}`;
+      for (const flow of [...truthy, ...falsy]) {
+        if (!flow.exclusiveGroup) {
+          flow.exclusiveGroup = groupName;
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Calculate priority and childComponentsControlled for a flow.
+ *
+ * Priority factors (in order of importance):
+ * 1. Controls rendering of child components (more components = higher priority)
+ * 2. Controls JSX rendering (impact = 'high')
+ * 3. Number of conditions required
+ */
+function calculateFlowPriority(
+  flow: ExecutionFlow,
+  gatingPathToChildren: Map<string, string[]>,
+): void {
+  // Find which child components this flow controls
+  const childComponentsControlled = new Set<string>();
+
+  for (const rv of flow.requiredValues) {
+    // Check if this required value's path gates any child components
+    const children = gatingPathToChildren.get(rv.attributePath);
+    if (children) {
+      // Only count truthy values as "enabling" the child component
+      // Falsy values would hide the child, not enable it
+      if (rv.comparison === 'truthy' || rv.comparison === 'equals') {
+        for (const child of children) {
+          childComponentsControlled.add(child);
+        }
+      }
+    }
+
+    // Also check without function call markers for broader matching
+    const simplifiedPath = rv.attributePath
+      .replace(/\(\)/g, '')
+      .replace(/\.functionCallReturnValue/g, '');
+    const childrenSimplified = gatingPathToChildren.get(simplifiedPath);
+    if (childrenSimplified) {
+      if (rv.comparison === 'truthy' || rv.comparison === 'equals') {
+        for (const child of childrenSimplified) {
+          childComponentsControlled.add(child);
+        }
+      }
+    }
+  }
+
+  // Set childComponentsControlled if any were found
+  if (childComponentsControlled.size > 0) {
+    flow.childComponentsControlled = Array.from(childComponentsControlled);
+
+    // Upgrade impact to 'high' if this flow controls child components
+    // A flow that controls which child components render DOES impact JSX rendering,
+    // even if the condition itself isn't directly in the JSX tree.
+    // This ensures flows like viewMode === 'screenshot' (which controls SafeScreenshot
+    // rendering via ScenarioViewer) get proper prioritization.
+    if (flow.impact !== 'high') {
+      flow.impact = 'high';
+    }
+
+    // Check if any controlled child component is a modal/dialog/overlay.
+    // Only truthy flows (which SHOW the component) should be marked as blocking.
+    // Falsy flows (which HIDE the component) should not be blocking.
+    const isTruthyFlow = flow.requiredValues.some(
+      (rv) => rv.comparison === 'truthy' || rv.comparison === 'equals',
+    );
+    if (
+      isTruthyFlow &&
+      Array.from(childComponentsControlled).some(isBlockingChildComponent)
+    ) {
+      flow.blocksOtherFlows = true;
+    }
+  }
+
+  // Calculate priority score
+  let priority = 0;
+
+  // Base priority by impact level
+  if (flow.impact === 'high') {
+    priority += 100;
+  } else if (flow.impact === 'medium') {
+    priority += 50;
+  } else {
+    priority += 25;
+  }
+
+  // Add priority for each child component controlled
+  // Each child component adds significant priority
+  priority += (flow.childComponentsControlled?.length ?? 0) * 75;
+
+  // Add small bonus for number of required values (more specific = slightly higher priority)
+  priority += Math.min(flow.requiredValues.length * 5, 25);
+
+  flow.priority = priority;
+}
+
+/**
+ * Get execution flows suitable for LLM scenario generation.
+ *
+ * Filters and sorts flows based on priority, ensuring diversity
+ * across exclusive groups and respecting min/max thresholds.
+ */
+export function getFlowsForScenarioGeneration(
+  flows: ExecutionFlow[],
+  options: {
+    /** Maximum number of flows to return (default: 20) */
+    maxFlows?: number;
+    /** Minimum priority threshold (default: 0) */
+    minPriority?: number;
+    /** Ensure at least one flow per exclusive group (default: false) */
+    ensureGroupDiversity?: boolean;
+    /** Return both included and excluded flows (default: false) */
+    includeExcludedFlows?: boolean;
+  } = {},
+):
+  | ExecutionFlow[]
+  | { includedFlows: ExecutionFlow[]; excludedFlows: ExecutionFlow[] } {
+  const {
+    maxFlows = 20,
+    minPriority = 0,
+    ensureGroupDiversity = false,
+    includeExcludedFlows = false,
+  } = options;
+
+  // Filter by minimum priority
+  let eligibleFlows = flows.filter((f) => (f.priority ?? 0) >= minPriority);
+
+  // Flows should already be sorted by priority, but ensure it
+  eligibleFlows = [...eligibleFlows].sort(
+    (a, b) => (b.priority ?? 0) - (a.priority ?? 0),
+  );
+
+  let includedFlows: ExecutionFlow[];
+
+  if (ensureGroupDiversity) {
+    // Ensure diversity across exclusive groups
+    includedFlows = selectFlowsWithGroupDiversity(eligibleFlows, maxFlows);
+  } else {
+    // Simple top-N selection
+    includedFlows = eligibleFlows.slice(0, maxFlows);
+  }
+
+  if (includeExcludedFlows) {
+    const includedIds = new Set(includedFlows.map((f) => f.id));
+    const excludedFlows = flows.filter((f) => !includedIds.has(f.id));
+    return { includedFlows, excludedFlows };
+  }
+
+  return includedFlows;
+}
+
+/**
+ * Build a map of attribute-value pairs to help identify related flows.
+ * Flows with the same attributePath but different values are considered "value siblings".
+ * For example, viewMode='interactive' and viewMode='screenshot' are value siblings.
+ */
+function buildValueGroupMap(flows: ExecutionFlow[]): Map<string, string[]> {
+  // Map from attributePath to array of (flowId, value) pairs
+  const pathToValues = new Map<
+    string,
+    Array<{ flowId: string; value: string }>
+  >();
+
+  for (const flow of flows) {
+    for (const rv of flow.requiredValues) {
+      // Only consider equals comparisons with specific values (not truthy/falsy)
+      if (
+        rv.comparison === 'equals' &&
+        rv.value &&
+        rv.value !== 'truthy' &&
+        rv.value !== 'falsy'
+      ) {
+        // Normalize the attributePath for comparison
+        const normalizedPath = rv.attributePath
+          .toLowerCase()
+          .replace(/[^a-z0-9]/g, '');
+
+        if (!pathToValues.has(normalizedPath)) {
+          pathToValues.set(normalizedPath, []);
+        }
+        pathToValues
+          .get(normalizedPath)!
+          .push({ flowId: flow.id, value: rv.value });
+      }
+    }
+  }
+
+  // Now create the value group map: flowId -> list of sibling flowIds
+  const valueGroupMap = new Map<string, string[]>();
+
+  for (const [, flowValues] of pathToValues) {
+    // Only create groups if there are multiple different values for the same path
+    const uniqueValues = new Set(flowValues.map((fv) => fv.value));
+    if (uniqueValues.size > 1 && flowValues.length <= 10) {
+      // This attribute has multiple values, so all flows are siblings.
+      // Skip large groups (>10 flows) — these are typically shared gating conditions
+      // (like route params) that would dominate the selection by pulling in too many
+      // siblings and displacing higher-priority flows.
+      const siblingIds = flowValues.map((fv) => fv.flowId);
+      for (const fv of flowValues) {
+        valueGroupMap.set(
+          fv.flowId,
+          siblingIds.filter((id) => id !== fv.flowId),
+        );
+      }
+    }
+  }
+
+  return valueGroupMap;
+}
+
+/**
+ * Select flows ensuring diversity across exclusive groups AND attribute values.
+ * Guarantees:
+ * 1. At least one flow per exclusive group
+ * 2. When a flow with a specific attribute value is selected, include sibling values too
+ */
+function selectFlowsWithGroupDiversity(
+  flows: ExecutionFlow[],
+  maxFlows: number,
+): ExecutionFlow[] {
+  const selected: ExecutionFlow[] = [];
+  const selectedIds = new Set<string>();
+  const groupsRepresented = new Set<string>();
+
+  // Build value group map to identify sibling flows
+  const valueGroupMap = buildValueGroupMap(flows);
+
+  // First pass: ensure at least one flow per exclusive group
+  for (const flow of flows) {
+    if (selectedIds.has(flow.id)) continue;
+    if (selected.length >= maxFlows) break;
+
+    if (flow.exclusiveGroup && !groupsRepresented.has(flow.exclusiveGroup)) {
+      selected.push(flow);
+      selectedIds.add(flow.id);
+      groupsRepresented.add(flow.exclusiveGroup);
+    }
+  }
+
+  // Second pass: fill remaining slots with highest priority flows
+  // But also include sibling value flows when we select a flow with a specific value
+  for (const flow of flows) {
+    if (selectedIds.has(flow.id)) continue;
+    if (selected.length >= maxFlows) break;
+
+    selected.push(flow);
+    selectedIds.add(flow.id);
+
+    // Check if this flow has sibling value flows that should also be included
+    const siblingIds = valueGroupMap.get(flow.id);
+    if (siblingIds && siblingIds.length > 0) {
+      // Try to include sibling flows (different values of the same attribute)
+      for (const siblingId of siblingIds) {
+        if (selectedIds.has(siblingId)) continue;
+        if (selected.length >= maxFlows) break;
+
+        const siblingFlow = flows.find((f) => f.id === siblingId);
+        if (siblingFlow) {
+          selected.push(siblingFlow);
+          selectedIds.add(siblingId);
+        }
+      }
+    }
+  }
+
+  // Re-sort by priority to maintain consistent ordering
+  return selected.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+}

package/analyzer-template/packages/ai/src/lib/generateExecutionFlowsFromConditionalEffects.ts

@@ -18,7 +18,7 @@ export interface GenerateExecutionFlowsOptions {
   /** Map of controllable paths to their types (for path resolution) */
   attributesMap?: Record<string, string>;
   /** Map from local variable names to data sources */
-  equivalentSignatureVariables?: Record<string, string>;
+  equivalentSignatureVariables?: Record<string, string | string[]>;
   /** Map from full paths to short paths */
   fullToShortPathMap?: Record<string, string>;
   /**