@codeyam/codeyam-cli 0.1.0-staging.323686 → 0.1.0-staging.483fdc2

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

@@ -18,6 +18,7 @@ import type {
   CompoundConditional,
   DerivedVariableOperation,
   DerivedVariableInfo,
+  JsxRenderingUsage,
 } from './astScopes/types';
 import type { EnrichedConditionalUsage } from './worker/SerializableDataStructure';
 import resolvePathToControllable from './resolvePathToControllable';
@@ -32,7 +33,7 @@ export interface ChildComponentConditionalData {
   /** Child's conditional usages keyed by variable name (may include sourceDataPath from enrichment) */
   conditionalUsages: Record<string, ExtendedConditionalUsage[]>;
   /** Child's equivalent signature variables (maps internal paths to prop paths) */
-  equivalentSignatureVariables: Record<string, string>;
+  equivalentSignatureVariables: Record<string, string | string[]>;
   /** Child's compound conditionals */
   compoundConditionals: CompoundConditional[];
   /**
@@ -41,6 +42,11 @@ export interface ChildComponentConditionalData {
    * then `hasAnalysis` is a gating condition for all of ChildComponent's flows.
    */
   gatingConditions?: ConditionalUsage[];
+  /**
+   * Child's JSX rendering usages (arrays rendered via .map(), text interpolation).
+   * These generate "variation flows" for different array lengths.
+   */
+  jsxRenderingUsages?: JsxRenderingUsage[];
 }
 
 export interface GenerateFlowsFromConditionalsArgs {
@@ -51,7 +57,7 @@ export interface GenerateFlowsFromConditionalsArgs {
   /** Map of controllable paths to their types */
   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>;
   /**
@@ -73,6 +79,21 @@ export interface GenerateFlowsFromConditionalsArgs {
    * to `currentRun.entityShas` when `isInCurrentRun` isn't in conditionalUsages.
    */
   derivedVariables?: Record<string, DerivedVariableInfo>;
+  /**
+   * Optional map of child prop paths to their actual data sources.
+   * Used when child props flow through useState but ultimately come from
+   * mockable data sources (e.g., API calls, fetchers).
+   *
+   * Example:
+   * - "WorkoutsView().signature[0].workouts" → "createClient()...functionCallReturnValue.data"
+   *
+   * When a child path translates to a useState value, we check this map
+   * to find the real data source that can be mocked.
+   */
+  sourceEquivalencies?: Record<
+    string,
+    Array<{ scopeNodeName: string; schemaPath: string }>
+  >;
 }
 
 /**
@@ -117,7 +138,7 @@ function expandDerivedVariableToSources(
   path: string,
   conditionalUsages: Record<string, ConditionalUsage[]>,
   attributesMap: Record<string, string>,
-  equivalentSignatureVariables: Record<string, string>,
+  equivalentSignatureVariables: Record<string, string | string[]>,
   fullToShortPathMap: Record<string, string>,
   visited: Set<string> = new Set(),
   derivedVariables?: Record<string, DerivedVariableInfo>,
@@ -387,6 +408,20 @@ function findInAttributesMapForPath(
   return null;
 }
 
+/**
+ * Generate a slug from a path for use in flow IDs and exclusive groups.
+ */
+function pathToSlug(path: string): string {
+  return path
+    .replace(/\[\d+\]/g, '')
+    .replace(/\[\]/g, '')
+    .replace(/\(\)/g, '')
+    .replace(/\.functionCallReturnValue/g, '')
+    .replace(/[<>]/g, '')
+    .replace(/\./g, '-')
+    .toLowerCase();
+}
+
 /**
  * Generate a human-readable name from a path.
  * Extracts the last meaningful part of the path.
@@ -732,8 +767,8 @@ function normalizePathForDeduplication(
  */
 function translateChildPathToParent(
   childPath: string,
-  childEquivalentSignatureVariables: Record<string, string>,
-  parentEquivalentSignatureVariables: Record<string, string>,
+  childEquivalentSignatureVariables: Record<string, string | string[]>,
+  parentEquivalentSignatureVariables: Record<string, string | string[]>,
   childName: string,
 ): string | null {
   // Extract the root variable from the child path
@@ -760,7 +795,11 @@ function translateChildPathToParent(
 
   // Look up the child's equivalence for this root variable
   // e.g., childEquiv[selectedScenario] = "signature[0].selectedScenario"
-  const childPropPath = childEquivalentSignatureVariables[rootVar];
+  // Handle array case (OR expressions) - use first element if array
+  const rawChildPropPath = childEquivalentSignatureVariables[rootVar];
+  const childPropPath = Array.isArray(rawChildPropPath)
+    ? rawChildPropPath[0]
+    : rawChildPropPath;
 
   if (!childPropPath) {
     // No mapping found - this might be internal state, not a prop
@@ -773,7 +812,11 @@ function translateChildPathToParent(
 
   // Look up parent's equivalence to find what value was passed to this prop
   // e.g., parentEquiv["ChildName().signature[0].selectedScenario"] = "selectedScenario"
-  const parentValue = parentEquivalentSignatureVariables[fullChildPropPath];
+  // Handle array case (OR expressions) - use first element if array
+  const rawParentValue = parentEquivalentSignatureVariables[fullChildPropPath];
+  const parentValue = Array.isArray(rawParentValue)
+    ? rawParentValue[0]
+    : rawParentValue;
 
   if (!parentValue) {
     // No parent mapping found - log ALL parent keys that contain the childName
@@ -800,6 +843,7 @@ export default function generateExecutionFlowsFromConditionals(
     fullToShortPathMap,
     childComponentData,
     derivedVariables,
+    sourceEquivalencies,
   } = args;
 
   const flows: ExecutionFlow[] = [];
@@ -1771,6 +1815,69 @@ export default function generateExecutionFlowsFromConditionals(
               }
             }
 
+            // Fallback 2: Try sourceEquivalencies to find the actual data source
+            // This handles the case where props flow through useState but originate
+            // from a mockable data source (e.g., API call, fetcher).
+            //
+            // Example: WorkoutsView receives `workouts` prop which in parent is stored
+            // in useState, but ultimately comes from a Supabase query.
+            // sourceEquivalencies tells us: "WorkoutsView().signature[0].workouts" → "createClient()...data"
+            if (!resolvedPath && sourceEquivalencies) {
+              // Build the child prop path to look up in sourceEquivalencies
+              // Format: "ChildName().signature[0].propName"
+              // First, find what prop this child path maps to
+              let childPropName: string | null = null;
+              for (const [varName, varPath] of Object.entries(
+                childData.equivalentSignatureVariables,
+              )) {
+                // Check if childPath starts with this variable name
+                // e.g., childPath = "workouts.length", varName = "workouts", varPath = "signature[0].workouts"
+                if (
+                  childPath === varName ||
+                  childPath.startsWith(`${varName}.`)
+                ) {
+                  childPropName = varName;
+                  break;
+                }
+              }
+
+              if (childPropName) {
+                // Build the full sourceEquivalencies key
+                const sourceEquivKey = `${childName}().signature[0].${childPropName}`;
+
+                const sourceEquivEntry = sourceEquivalencies[sourceEquivKey];
+                if (sourceEquivEntry && sourceEquivEntry.length > 0) {
+                  const dataSourcePath = sourceEquivEntry[0].schemaPath;
+
+                  // Check if this data source path is controllable
+                  const dataSourceResolution = resolvePathToControllable(
+                    dataSourcePath,
+                    attributesMap,
+                    equivalentSignatureVariables,
+                    fullToShortPathMap,
+                  );
+
+                  if (
+                    dataSourceResolution.isControllable &&
+                    dataSourceResolution.resolvedPath
+                  ) {
+                    // Preserve any suffix from the child path
+                    // e.g., childPath = "workouts.length" → suffix = ".length"
+                    const suffix = childPath.startsWith(`${childPropName}.`)
+                      ? childPath.slice(childPropName.length)
+                      : '';
+                    resolvedPath = dataSourceResolution.resolvedPath + suffix;
+
+                    if (shouldDebugChild) {
+                      console.log(
+                        `[DEBUG CHILD ${childName}]   sourceEquivalencies fallback SUCCESS: using data source ${resolvedPath}`,
+                      );
+                    }
+                  }
+                }
+              }
+            }
+
             // If still not resolved after fallback, skip
             if (!resolvedPath) {
               if (shouldDebugChild) {
@@ -1970,6 +2077,189 @@ export default function generateExecutionFlowsFromConditionals(
           }
         }
       }
+
+      // Process child's jsxRenderingUsages (array.map flows)
+      // This generates array variation flows (empty, few, many) for arrays rendered in child
+      if (childData.jsxRenderingUsages) {
+        for (const jsxUsage of childData.jsxRenderingUsages) {
+          // Translate the child path to a parent path
+          const translatedPath = translateChildPathToParent(
+            jsxUsage.path,
+            childData.equivalentSignatureVariables,
+            equivalentSignatureVariables,
+            childName,
+          );
+
+          if (!translatedPath) {
+            continue;
+          }
+
+          // Resolve to controllable path in parent context
+          const resolution = resolvePathToControllable(
+            translatedPath,
+            attributesMap,
+            equivalentSignatureVariables,
+            fullToShortPathMap,
+          );
+
+          let resolvedPath = resolution.resolvedPath;
+
+          // Try sourceEquivalencies fallback if not controllable
+          if (!resolution.isControllable || !resolvedPath) {
+            if (sourceEquivalencies) {
+              // Build the sourceEquivalencies key
+              // The child path (e.g., "workouts") maps to a prop path (e.g., "signature[0].workouts")
+              let childPropName: string | null = null;
+              for (const [varName, varPath] of Object.entries(
+                childData.equivalentSignatureVariables,
+              )) {
+                if (
+                  jsxUsage.path === varName ||
+                  jsxUsage.path.startsWith(`${varName}.`)
+                ) {
+                  childPropName = varName;
+                  break;
+                }
+              }
+
+              if (childPropName) {
+                const sourceEquivKey = `${childName}().signature[0].${childPropName}`;
+                const sourceEquivEntry = sourceEquivalencies[sourceEquivKey];
+
+                if (sourceEquivEntry && sourceEquivEntry.length > 0) {
+                  const dataSourcePath = sourceEquivEntry[0].schemaPath;
+
+                  const dataSourceResolution = resolvePathToControllable(
+                    dataSourcePath,
+                    attributesMap,
+                    equivalentSignatureVariables,
+                    fullToShortPathMap,
+                  );
+
+                  if (
+                    dataSourceResolution.isControllable &&
+                    dataSourceResolution.resolvedPath
+                  ) {
+                    resolvedPath = dataSourceResolution.resolvedPath;
+                  }
+                }
+              }
+            }
+          }
+
+          if (!resolvedPath) {
+            continue;
+          }
+
+          // Check for duplicates
+          const normalizedPath = normalizePathForDeduplication(
+            resolvedPath,
+            fullToShortPathMap,
+          );
+          const dedupeKey = `${normalizedPath}:${jsxUsage.renderingType}`;
+          if (seenNormalizedPaths.has(dedupeKey)) {
+            continue;
+          }
+          seenNormalizedPaths.add(dedupeKey);
+
+          // Generate array variation flows for array-map rendering
+          if (jsxUsage.renderingType === 'array-map') {
+            const baseName = generateNameFromPath(resolvedPath);
+            const pathSlug = pathToSlug(resolvedPath);
+            const exclusiveGroup = `array-length-${pathSlug}`;
+
+            // Empty array flow
+            const emptyFlow: ExecutionFlow = {
+              id: `${pathSlug}-empty-array`,
+              name: `${baseName} Empty`,
+              description: `When ${baseName.toLowerCase()} array is empty`,
+              requiredValues: [
+                {
+                  attributePath: resolvedPath,
+                  value: '0',
+                  comparison: 'length<',
+                  valueType: 'array',
+                },
+                ...gatingRequiredValues,
+              ],
+              impact: 'medium',
+              exclusiveGroup,
+              sourceLocation: jsxUsage.sourceLocation
+                ? {
+                    lineNumber: jsxUsage.sourceLocation.lineNumber,
+                    column: jsxUsage.sourceLocation.column,
+                  }
+                : undefined,
+              codeSnippet: jsxUsage.sourceLocation?.codeSnippet,
+            };
+
+            if (!seenFlowIds.has(emptyFlow.id)) {
+              seenFlowIds.add(emptyFlow.id);
+              flows.push(emptyFlow);
+            }
+
+            // Few items flow (1-3)
+            const fewFlow: ExecutionFlow = {
+              id: `${pathSlug}-few-items`,
+              name: `${baseName} Few Items`,
+              description: `When ${baseName.toLowerCase()} array has 1-3 items`,
+              requiredValues: [
+                {
+                  attributePath: resolvedPath,
+                  value: '3',
+                  comparison: 'length<',
+                  valueType: 'array',
+                },
+                ...gatingRequiredValues,
+              ],
+              impact: 'low',
+              exclusiveGroup,
+              sourceLocation: jsxUsage.sourceLocation
+                ? {
+                    lineNumber: jsxUsage.sourceLocation.lineNumber,
+                    column: jsxUsage.sourceLocation.column,
+                  }
+                : undefined,
+              codeSnippet: jsxUsage.sourceLocation?.codeSnippet,
+            };
+
+            if (!seenFlowIds.has(fewFlow.id)) {
+              seenFlowIds.add(fewFlow.id);
+              flows.push(fewFlow);
+            }
+
+            // Many items flow (10+)
+            const manyFlow: ExecutionFlow = {
+              id: `${pathSlug}-many-items`,
+              name: `${baseName} Many Items`,
+              description: `When ${baseName.toLowerCase()} array has many items`,
+              requiredValues: [
+                {
+                  attributePath: resolvedPath,
+                  value: '10',
+                  comparison: 'length>',
+                  valueType: 'array',
+                },
+                ...gatingRequiredValues,
+              ],
+              impact: 'low',
+              exclusiveGroup,
+              sourceLocation: jsxUsage.sourceLocation
+                ? {
+                    lineNumber: jsxUsage.sourceLocation.lineNumber,
+                    column: jsxUsage.sourceLocation.column,
+                  }
+                : undefined,
+              codeSnippet: jsxUsage.sourceLocation?.codeSnippet,
+            };
+
+            if (!seenFlowIds.has(manyFlow.id)) {
+              seenFlowIds.add(manyFlow.id);
+              flows.push(manyFlow);
+            }
+          }
+        }
+      }
     }
   }
 

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

@@ -19,7 +19,7 @@ export interface GenerateFlowsFromJsxUsagesArgs {
   /** Map of controllable paths to their types */
   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>;
   /** Structure map for type lookup */

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

@@ -7,58 +7,12 @@ import {
 
 export interface Statement {
   structure: { [key: string]: string };
-  equivalentVariables: { [key: string]: string };
+  // Supports multiple equivalencies per key for OR expressions (e.g., x = a || b)
+  equivalentVariables: { [key: string]: string | string[] };
   llmCall?: LlmCall;
 }
 
 export default function mergeStatements(statements: Statement[]) {
-  // Debug: Log input statements to understand what we're merging
-  const hasStateStructure = statements.some((s) =>
-    Object.keys(s.structure || {}).some(
-      (k) => k === 'state' || k.includes('state'),
-    ),
-  );
-  const hasStateEquiv = statements.some((s) =>
-    Object.keys(s.equivalentVariables || {}).some(
-      (k) => k === 'state' || k.includes('state'),
-    ),
-  );
-  if (hasStateStructure || hasStateEquiv) {
-    console.log(
-      `[UNION-TYPE] mergeStatements INPUT: ${statements.length} statements`,
-    );
-    statements.forEach((s, i) => {
-      const stateInStructure = Object.entries(s.structure || {}).filter(
-        ([k]) => k === 'state' || k.includes('state'),
-      );
-      const stateInEquiv = Object.entries(s.equivalentVariables || {}).filter(
-        ([k]) => k === 'state' || k.includes('state'),
-      );
-      const sigInEquiv = Object.entries(s.equivalentVariables || {}).filter(
-        ([k, v]) => k === 'state' || v === 'signature[0]',
-      );
-      if (
-        stateInStructure.length > 0 ||
-        stateInEquiv.length > 0 ||
-        sigInEquiv.length > 0
-      ) {
-        console.log(`[UNION-TYPE]   Statement ${i}:`);
-        if (stateInStructure.length > 0)
-          console.log(
-            `[UNION-TYPE]     structure: ${JSON.stringify(Object.fromEntries(stateInStructure))}`,
-          );
-        if (stateInEquiv.length > 0)
-          console.log(
-            `[UNION-TYPE]     equivalentVariables (state): ${JSON.stringify(Object.fromEntries(stateInEquiv))}`,
-          );
-        if (sigInEquiv.length > 0)
-          console.log(
-            `[UNION-TYPE]     equivalentVariables (sig): ${JSON.stringify(Object.fromEntries(sigInEquiv))}`,
-          );
-      }
-    });
-  }
-
   // This should be handled by the AST Analyzer but it currently has a bug
   const ensureFunctionCallReturnValue = (path: string, value: string) => {
     if (path.endsWith(')') && value !== 'function') {
@@ -172,12 +126,54 @@ export default function mergeStatements(statements: Statement[]) {
   // settingsData → fetcher.data.data uses fetcher::cyDuplicateKey1::.data.data
   const activeRemappings: Record<string, string> = {};
 
+  // Helper to normalize value to array and process
+  const normalizeValue = (value: string | string[]): string[] =>
+    Array.isArray(value) ? value : [value];
+
   const equivalentVariables = statements.reduce((acc: any, result) => {
-    for (const [key, value] of Object.entries(
+    for (const [key, rawValue] of Object.entries(
       result.equivalentVariables ?? {},
     )) {
+      // Handle arrays from AST analyzer (OR expressions like x = a || b)
+      // These should be preserved as arrays to track all sources
+      if (Array.isArray(rawValue)) {
+        const keyOptions = deBinaryPath(key);
+        const validValues = rawValue.filter(
+          (v): v is string => typeof v === 'string' && v.length > 0,
+        );
+        if (validValues.length === 0) continue;
+
+        // Process each array value through deBinaryPath
+        const allValueOptions: string[] = [];
+        for (const value of validValues) {
+          const valueOptions = deBinaryPath(value);
+          allValueOptions.push(...valueOptions);
+        }
+
+        // Remove duplicates while preserving order
+        const uniqueValueOptions = [...new Set(allValueOptions)];
+        const finalValue =
+          uniqueValueOptions.length === 1
+            ? uniqueValueOptions[0]
+            : uniqueValueOptions;
+
+        delete result.equivalentVariables[key];
+        if (keyOptions.length >= 2) {
+          for (const keyOption of keyOptions) {
+            result.equivalentVariables[keyOption] = finalValue;
+          }
+        } else {
+          result.equivalentVariables[keyOptions[0]] = finalValue;
+        }
+        continue;
+      }
+
+      // Original logic for string values with potential binary expressions in the string
+      const firstValue = rawValue;
+      if (!firstValue) continue;
+
       const keyOptions = deBinaryPath(key);
-      const valueOptions = deBinaryPath(value);
+      const valueOptions = deBinaryPath(firstValue);
       delete result.equivalentVariables[key];
       if (keyOptions.length === 2) {
         if (valueOptions.length === 2) {
@@ -199,27 +195,38 @@ export default function mergeStatements(statements: Statement[]) {
       }
     }
 
-    for (const [key, value] of Object.entries(
+    for (const [key, rawValue] of Object.entries(
       result.equivalentVariables ?? {},
     )) {
+      // Normalize to array for consistent handling
+      const values = normalizeValue(rawValue);
+
       // Apply any active remappings to the VALUE, but ONLY for property paths
       // e.g., if fetcher was remapped to fetcher::cyDuplicateKey1::,
       // then "fetcher.data.data" should become "fetcher::cyDuplicateKey1::.data.data"
       // However, we should NOT remap standalone variable references like "description"
       // because that would lose type information from the original variable.
-      let remappedValue = value;
-      for (const [originalKey, remappedKey] of Object.entries(
-        activeRemappings,
-      )) {
-        // Only remap if the value is a property path (contains a dot after the key)
-        // This preserves type information for simple variable references
-        const keyRegex = new RegExp(
-          `^${originalKey.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?=\\.)`,
-        );
-        if (keyRegex.test(remappedValue)) {
-          remappedValue = remappedValue.replace(keyRegex, remappedKey);
+      const remappedValues = values.map((value) => {
+        let remappedValue = value;
+        for (const [originalKey, remappedKey] of Object.entries(
+          activeRemappings,
+        )) {
+          // Only remap if the value is a property path (contains a dot after the key)
+          // This preserves type information for simple variable references
+          const keyRegex = new RegExp(
+            `^${originalKey.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?=\\.)`,
+          );
+          if (keyRegex.test(remappedValue)) {
+            remappedValue = remappedValue.replace(keyRegex, remappedKey);
+          }
         }
-      }
+        return remappedValue;
+      });
+
+      // Use array if multiple values, string if single
+      const remappedValue =
+        remappedValues.length === 1 ? remappedValues[0] : remappedValues;
+      const firstRemappedValue = remappedValues[0];
 
       if (acc[key]) {
         if (acc[key] === remappedValue) continue;
@@ -247,45 +254,32 @@ export default function mergeStatements(statements: Statement[]) {
   // If we have equivalentVariables[A] = B, and structure[A] is more specific than structure[B],
   // then update structure[B] to match structure[A]
   // This handles cases like: "state" -> "signature[0]" where "state" has a union type
-
-  // Debug: Log union types in merged structure
-  const unionTypesInStructure = Object.entries(structure).filter(
-    ([_, v]) => typeof v === 'string' && v.includes("'") && v.includes(' | '),
-  );
-  if (unionTypesInStructure.length > 0) {
-    console.log(
-      `[UNION-TYPE] mergeStatements: Found ${unionTypesInStructure.length} union types in merged structure`,
-    );
-    unionTypesInStructure.forEach(([k, v]) =>
-      console.log(`[UNION-TYPE]   structure["${k}"] = ${v}`),
-    );
-    console.log(
-      `[UNION-TYPE] mergeStatements: equivalentVariables = ${JSON.stringify(equivalentVariables)}`,
-    );
-  }
-
-  for (const [source, target] of Object.entries(equivalentVariables) as [
-    string,
+  for (const [source, rawTarget] of Object.entries(equivalentVariables) as [
     string,
+    string | string[],
   ][]) {
+    // Normalize to array for consistent handling
+    const targets = Array.isArray(rawTarget) ? rawTarget : [rawTarget];
     const sourceType = structure[source];
-    const targetType = structure[target];
 
-    // Check if source has a more specific type (union type vs generic type)
-    if (sourceType) {
-      const sourceIsUnion =
-        sourceType.includes("'") && sourceType.includes(' | ');
+    for (const target of targets) {
+      if (typeof target !== 'string') continue;
 
-      if (sourceIsUnion) {
-        // Target doesn't exist or is generic - propagate the union type
-        const targetIsGeneric =
-          !targetType || targetType === 'string' || targetType === 'unknown';
+      const targetType = structure[target];
 
-        if (targetIsGeneric) {
-          console.log(
-            `[UNION-TYPE] mergeStatements: Propagating "${source}" (${sourceType}) -> "${target}"`,
-          );
-          structure[target] = sourceType;
+      // Check if source has a more specific type (union type vs generic type)
+      if (sourceType) {
+        const sourceIsUnion =
+          sourceType.includes("'") && sourceType.includes(' | ');
+
+        if (sourceIsUnion) {
+          // Target doesn't exist or is generic - propagate the union type
+          const targetIsGeneric =
+            !targetType || targetType === 'string' || targetType === 'unknown';
+
+          if (targetIsGeneric) {
+            structure[target] = sourceType;
+          }
         }
       }
     }

package/analyzer-template/packages/ai/src/lib/promptGenerators/gatherAttributesMap.ts

@@ -139,16 +139,19 @@ export function gatherAttributesMap(
       // Use merged type if available, otherwise fall back to isolated type
       const typeValue =
         mergedSignatureSchema[key] ?? isolatedSignatureSchema[key];
-      const equivalentSignatureVariable =
-        equivalentSignatureVariables[keyParts[0]];
-      const equivalentSignatureVariableParts = splitOutsideParenthesesAndArrays(
-        equivalentSignatureVariable,
-      );
+      // Handle array case (OR expressions) - use first element if array
+      const rawEquivalent = equivalentSignatureVariables[keyParts[0]];
+      const equivalentSignatureVariable = Array.isArray(rawEquivalent)
+        ? rawEquivalent[0]
+        : rawEquivalent;
+      const equivalentSignatureVariableParts = equivalentSignatureVariable
+        ? splitOutsideParenthesesAndArrays(equivalentSignatureVariable)
+        : [];
       if (
         equivalentSignatureVariable &&
-        !equivalentSignatureVariableParts[0].includes('(')
+        !equivalentSignatureVariableParts[0]?.includes('(')
       ) {
-        const equivalentKey = equivalentSignatureVariables[keyParts[0]];
+        const equivalentKey = equivalentSignatureVariable;
         const equivalentPath = joinParenthesesAndArrays([
           equivalentKey,
           ...keyParts.slice(1),