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

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

@@ -0,0 +1,710 @@
+/**
+ * Generates execution flows using pure static analysis.
+ *
+ * This module has been refactored to use deterministic flow generation
+ * 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.
+ */
+
+import {
+  DataStructure,
+  Entity,
+  ExecutionFlow,
+  ConditionalEffect,
+} from '~codeyam/types';
+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 } 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'>;
+  mergedDataStructure: Omit<DataStructure, 'equivalentSignatureVariables'>;
+  /** @deprecated Model is no longer used - execution flows are generated via static analysis */
+  model?: AI.Model;
+  /**
+   * Optional map of child entity names to their metadata.
+   * Used for merging child component execution flows into the parent.
+   * The caller should:
+   * 1. Look at childBoundaryGatingConditions to see which children need metadata
+   * 2. Find those entities (via importedExports or database lookup)
+   * 3. Pass their metadata here
+   */
+  childEntityMetadata?: Record<string, Entity['metadata']>;
+}
+
+export default function generateExecutionFlows({
+  entity,
+  mergedDataStructure,
+  childEntityMetadata,
+}: GenerateExecutionFlowsArgs) {
+  awsLog(`CodeYam: Generating execution flows (static analysis)`, {
+    filePath: entity.filePath,
+    entityName: entity.name,
+  });
+
+  const isolatedDataStructure = entity.metadata?.isolatedDataStructure;
+
+  const equivalentSignatureVariables =
+    isolatedDataStructure?.equivalentSignatureVariables ?? {};
+  const { attributesMap, associationMap } = gatherAttributesMap(
+    isolatedDataStructure ?? mergedDataStructure,
+    mergedDataStructure,
+    equivalentSignatureVariables,
+    true,
+  );
+
+  // Clean the attributes map to remove primitive-returning array method paths
+  clearAttributesFromMapping(attributesMap);
+
+  if (Object.keys(attributesMap).length === 0) {
+    console.log(
+      `CodeYam: No valid attributes found for ${entity.filePath} ${entity.name}`,
+    );
+    return {
+      executionFlows: [],
+      llmCall: null as LlmCall | null,
+    };
+  }
+
+  // Build merged schema for type inference
+  const mergedSchemaForTypeLookup = Object.fromEntries(
+    Object.entries(mergedDataStructure.signatureSchema ?? {})
+      .filter(([k]) => k.startsWith('signature['))
+      .map(([k, v]) => [k.replace(/^signature\[\d+\]\./, ''), v]),
+  );
+
+  // Resolve unknown types using heuristics
+  const resolvedAttributesMap = fillInDirectSchemaGapsAndUnknowns({
+    scopeName: entity.name,
+    schema: { ...attributesMap },
+    mergedSchema: mergedSchemaForTypeLookup,
+  });
+
+  // Build fullToShortPathMap from associationMap
+  // 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 [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 ?? {};
+  const compoundConditionals: CompoundConditional[] =
+    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:
+  // 1. childBoundaryGatingConditions - which parent conditions gate each child
+  // 2. childEntityMetadata - passed by caller after looking up child entities
+  const childBoundaryGatingConditions: Record<string, ConditionalUsage[]> =
+    entity.metadata?.isolatedDataStructure?.childBoundaryGatingConditions ?? {};
+
+  // Build childComponentData using the provided childEntityMetadata
+  // The caller is responsible for looking up child entities (via importedExports
+  // or database) and passing their metadata here
+  const childComponentData: Record<string, ChildComponentConditionalData> = {};
+  if (childEntityMetadata) {
+    for (const [childName, gatingConditions] of Object.entries(
+      childBoundaryGatingConditions,
+    )) {
+      const childMeta = childEntityMetadata[childName];
+      const childIsolated = childMeta?.isolatedDataStructure;
+
+      if (childIsolated) {
+        childComponentData[childName] = {
+          conditionalUsages: childIsolated.conditionalUsages ?? {},
+          equivalentSignatureVariables:
+            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,
+    attributesMap: resolvedAttributesMap,
+    equivalentSignatureVariables,
+    fullToShortPathMap,
+    childComponentData:
+      Object.keys(childComponentData).length > 0
+        ? childComponentData
+        : undefined,
+    derivedVariables,
+    sourceEquivalencies: mergedDataStructure.sourceEquivalencies,
+  });
+
+  console.log(
+    `CodeYam: Generated ${conditionalsBasedFlows.length} flows from conditional usages`,
+  );
+
+  // Generate flows from conditional effects (setter calls inside conditionals)
+  // Pass resolution context so paths can be resolved to controllable data sources
+  const effectsBasedFlows = generateExecutionFlowsFromConditionalEffects(
+    conditionalEffects,
+    {
+      attributesMap: resolvedAttributesMap,
+      equivalentSignatureVariables,
+      fullToShortPathMap,
+      conditionalUsages,
+    },
+  );
+
+  console.log(
+    `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>();
+
+  // Add effects-based flows first (higher priority)
+  for (const flow of effectsBasedFlows) {
+    if (!seenIds.has(flow.id)) {
+      seenIds.add(flow.id);
+      allFlows.push(flow);
+    }
+  }
+
+  // Add conditionals-based flows
+  for (const flow of conditionalsBasedFlows) {
+    if (!seenIds.has(flow.id)) {
+      seenIds.add(flow.id);
+      allFlows.push(flow);
+    }
+  }
+
+  // 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));
+}