@codeyam/codeyam-cli 0.1.0-staging.596f0eb → 0.1.0-staging.62d4615

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

@@ -0,0 +1,528 @@
+import type { ConditionalEffect, ConditionalUsage } from './astScopes/types';
+import type { ExecutionFlow } from '~codeyam/types';
+import type { EnrichedConditionalUsage } from './worker/SerializableDataStructure';
+import resolvePathToControllable from './resolvePathToControllable';
+
+/** Extended conditional usage type that may include sourceDataPath from enrichment */
+type ExtendedConditionalUsage = ConditionalUsage &
+  Partial<EnrichedConditionalUsage>;
+
+/**
+ * Options for generating execution flows from conditional effects
+ */
+export interface GenerateExecutionFlowsOptions {
+  /** Map of state variable names to their display names (for better naming) */
+  stateVariableNames?: Record<string, string>;
+  /** Map of state variable names to whether they typically block other content */
+  blocksOtherFlowsMap?: Record<string, boolean>;
+  /** 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 | string[]>;
+  /** Map from full paths to short paths */
+  fullToShortPathMap?: Record<string, string>;
+  /**
+   * Map of local variable paths to their enriched conditional usages.
+   * Used to look up sourceDataPath for conditions.
+   */
+  conditionalUsages?: Record<string, ExtendedConditionalUsage[]>;
+}
+
+/**
+ * Patterns that indicate a state variable controls modal/overlay/blocking content
+ */
+const BLOCKING_PATTERNS = [
+  /modal/i,
+  /overlay/i,
+  /dialog/i,
+  /popup/i,
+  /drawer/i,
+  /sheet/i,
+  /lightbox/i,
+  /backdrop/i,
+];
+
+/**
+ * Check if a state variable name suggests it controls blocking content
+ */
+function isBlockingStateVariable(stateVariable: string): boolean {
+  return BLOCKING_PATTERNS.some((pattern) => pattern.test(stateVariable));
+}
+
+/**
+ * Generate a human-readable name from a state variable and value
+ */
+function generateFlowName(
+  stateVariable: string,
+  value: string,
+  valueType: string,
+): string {
+  // Convert camelCase to Title Case with spaces
+  const humanReadable = stateVariable
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/^./, (str) => str.toUpperCase())
+    .trim();
+
+  // For boolean state, describe the state
+  if (valueType === 'boolean') {
+    if (value === 'true') {
+      // Check for common patterns
+      if (/^show/i.test(stateVariable)) {
+        return humanReadable.replace(/^Show\s*/i, '') + ' Visible';
+      }
+      if (/^is/i.test(stateVariable)) {
+        return humanReadable.replace(/^Is\s*/i, '') + ' Active';
+      }
+      if (/open$/i.test(stateVariable)) {
+        return humanReadable;
+      }
+      return humanReadable + ' Enabled';
+    } else {
+      if (/^show/i.test(stateVariable)) {
+        return humanReadable.replace(/^Show\s*/i, '') + ' Hidden';
+      }
+      if (/^is/i.test(stateVariable)) {
+        return humanReadable.replace(/^Is\s*/i, '') + ' Inactive';
+      }
+      if (/open$/i.test(stateVariable)) {
+        return humanReadable.replace(/Open$/i, 'Closed');
+      }
+      return humanReadable + ' Disabled';
+    }
+  }
+
+  // For string values, include the value in the name
+  if (valueType === 'string') {
+    const valueCapitalized =
+      value.charAt(0).toUpperCase() + value.slice(1).toLowerCase();
+    return `${humanReadable}: ${valueCapitalized}`;
+  }
+
+  return humanReadable;
+}
+
+/**
+ * Generate a flow ID from state variable and value
+ */
+function generateFlowId(stateVariable: string, value: string): string {
+  // Sanitize the value for use in an ID
+  const sanitizedValue = value
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+
+  return `${stateVariable}-${sanitizedValue}`;
+}
+
+/**
+ * Generate a description for the flow
+ */
+function generateFlowDescription(
+  stateVariable: string,
+  value: string,
+  valueType: string,
+  conditions: Array<{ path: string; requiredValue: string | boolean }>,
+): string {
+  const conditionDesc = conditions
+    .map((c) => {
+      if (typeof c.requiredValue === 'boolean') {
+        return c.requiredValue ? `${c.path} is truthy` : `${c.path} is falsy`;
+      }
+      return `${c.path} equals "${c.requiredValue}"`;
+    })
+    .join(' AND ');
+
+  if (valueType === 'boolean') {
+    const stateDesc = value === 'true' ? 'shown/enabled' : 'hidden/disabled';
+    return `${stateVariable} is ${stateDesc} when ${conditionDesc}`;
+  }
+
+  return `${stateVariable} is set to "${value}" when ${conditionDesc}`;
+}
+
+/**
+ * Convert a condition's requiredValue to comparison type
+ */
+function getComparisonType(
+  conditionType: 'truthiness' | 'comparison' | 'switch',
+  requiredValue: string | boolean,
+): 'equals' | 'truthy' | 'falsy' {
+  if (conditionType === 'truthiness') {
+    return requiredValue === true ? 'truthy' : 'falsy';
+  }
+  return 'equals';
+}
+
+/**
+ * Get the value string for the required value
+ */
+function getValueString(
+  conditionType: 'truthiness' | 'comparison' | 'switch',
+  requiredValue: string | boolean,
+): string {
+  if (conditionType === 'truthiness') {
+    return requiredValue === true ? 'truthy' : 'falsy';
+  }
+  return String(requiredValue);
+}
+
+/**
+ * Determine impact level based on effect type
+ */
+function determineImpact(
+  valueType: string,
+  stateVariable: string,
+): 'high' | 'medium' | 'low' {
+  // Boolean state changes typically have high impact (show/hide, enable/disable)
+  if (valueType === 'boolean') {
+    return 'high';
+  }
+
+  // Modal-related changes are high impact
+  if (isBlockingStateVariable(stateVariable)) {
+    return 'high';
+  }
+
+  // String state changes are typically medium impact
+  if (valueType === 'string') {
+    return 'medium';
+  }
+
+  // Default to medium
+  return 'medium';
+}
+
+/**
+ * Clean up sourceDataPath by removing redundant scope prefixes.
+ *
+ * This function ONLY handles the specific pattern where a scope name is
+ * duplicated before the hook call:
+ *
+ * Example:
+ * "useLoaderData<LoaderData>.useLoaderData<LoaderData>().functionCallReturnValue.entity.sha"
+ * → "useLoaderData<LoaderData>().functionCallReturnValue.entity.sha"
+ *
+ * For paths with multiple function calls (like fetch().json()), or paths
+ * that don't match the expected pattern, returns null to indicate the
+ * fallback resolution should be used.
+ */
+function cleanSourceDataPath(sourceDataPath: string): string | null {
+  // Count function call patterns - both empty () and with content (...)
+  // We detect multiple function calls by counting:
+  // 1. Empty () patterns
+  // 2. Patterns like functionName(...) - closing paren followed by dot or end
+  const emptyFnCalls = (sourceDataPath.match(/\(\)/g) || []).length;
+  const fnCallReturnValues = (
+    sourceDataPath.match(/\.functionCallReturnValue/g) || []
+  ).length;
+
+  // If there are multiple functionCallReturnValue occurrences, this is a chained call
+  // (e.g., fetch(...).functionCallReturnValue.json().functionCallReturnValue.data)
+  if (fnCallReturnValues > 1 || emptyFnCalls !== 1) {
+    // Multiple function calls - return null to use fallback resolution
+    return null;
+  }
+
+  // Find the "()" which marks the function call
+  const fnCallIndex = sourceDataPath.indexOf('()');
+
+  // Find where the function name starts (go back to find the start of this segment)
+  const beforeFnCall = sourceDataPath.slice(0, fnCallIndex);
+  const lastDotBeforeFn = beforeFnCall.lastIndexOf('.');
+
+  if (lastDotBeforeFn === -1) {
+    return sourceDataPath;
+  }
+
+  // Extract the scope prefix and the actual path
+  const scopePrefix = sourceDataPath.slice(0, lastDotBeforeFn);
+  const actualPath = sourceDataPath.slice(lastDotBeforeFn + 1);
+
+  // Verify this is actually a redundant scope prefix pattern
+  // The actualPath should start with something that matches the scopePrefix
+  // e.g., scopePrefix="useLoaderData<LoaderData>" and actualPath starts with "useLoaderData<LoaderData>()..."
+  if (!actualPath.startsWith(scopePrefix.split('.').pop() || '')) {
+    // Not a redundant prefix pattern - return the original path
+    return sourceDataPath;
+  }
+
+  return actualPath;
+}
+
+/**
+ * Find a path in attributesMap, using fullToShortPathMap to verify the path is controllable.
+ *
+ * IMPORTANT: Returns the FULL path (preserving data source context) when possible.
+ * This ensures execution flows can be traced back to specific data sources,
+ * which is critical when multiple data sources have the same property names
+ * (e.g., multiple useFetcher hooks all having 'state' and 'data').
+ *
+ * The attributesMap contains short relative paths (e.g., "entity.sha")
+ * The sourceDataPath contains full paths (e.g., "useLoaderData<LoaderData>().functionCallReturnValue.entity.sha")
+ * The fullToShortPathMap maps full paths to short paths
+ */
+function findInAttributesMapForPath(
+  path: string,
+  attributesMap: Record<string, string>,
+  fullToShortPathMap: Record<string, string>,
+): string | null {
+  // Direct match in attributesMap (already a short path)
+  if (path in attributesMap) {
+    return path;
+  }
+
+  // Try looking up the path in fullToShortPathMap to verify it's controllable
+  // IMPORTANT: Return the FULL path, not the short path, to preserve data source context
+  if (path in fullToShortPathMap) {
+    const shortPath = fullToShortPathMap[path];
+    if (shortPath in attributesMap) {
+      return path; // Return FULL path to preserve data source context
+    }
+  }
+
+  // Normalized match (array indices [N] → [])
+  const normalizedPath = path.replace(/\[\d+\]/g, '[]');
+  if (normalizedPath !== path) {
+    if (normalizedPath in attributesMap) {
+      return normalizedPath;
+    }
+    if (normalizedPath in fullToShortPathMap) {
+      const shortPath = fullToShortPathMap[normalizedPath];
+      if (shortPath in attributesMap) {
+        return normalizedPath; // Return normalized FULL path
+      }
+    }
+  }
+
+  // Try prefix matching for child paths
+  for (const attrPath of Object.keys(attributesMap)) {
+    if (path.startsWith(attrPath + '.') || path.startsWith(attrPath + '[')) {
+      return path;
+    }
+  }
+
+  // Try suffix matching: if the path ends with ".X.Y.Z" and attributesMap has "X.Y.Z"
+  // Return the FULL input path to preserve data source context
+  for (const attrPath of Object.keys(attributesMap)) {
+    if (
+      path.endsWith('.' + attrPath) ||
+      path.endsWith('.' + attrPath.replace(/\[\d+\]/g, '[]'))
+    ) {
+      return path; // Return FULL path, not short attrPath
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Resolve a condition path to a controllable data source path.
+ *
+ * Resolution strategy:
+ * 1. Look up sourceDataPath in conditionalUsages (pre-computed during AST analysis)
+ * 2. Fall back to resolvePathToControllable (variable resolution)
+ *
+ * @returns The resolved controllable path, or null if not controllable
+ */
+function resolveConditionPath(
+  localPath: string,
+  options?: GenerateExecutionFlowsOptions,
+): string | null {
+  if (!options) {
+    return null;
+  }
+
+  const {
+    attributesMap = {},
+    equivalentSignatureVariables = {},
+    fullToShortPathMap = {},
+    conditionalUsages = {},
+  } = options;
+
+  // 1. Try to use pre-computed sourceDataPath from conditionalUsages
+  const usagesForPath = conditionalUsages[localPath];
+  if (usagesForPath && usagesForPath.length > 0) {
+    const usage = usagesForPath[0];
+    if (usage.sourceDataPath) {
+      // Clean up the sourceDataPath - it may have redundant scope prefixes
+      // Returns null for paths that don't match the expected pattern (e.g., multiple function calls)
+      const cleanedPath = cleanSourceDataPath(usage.sourceDataPath);
+
+      if (cleanedPath) {
+        // Verify the cleaned path exists in attributesMap (using fullToShortPathMap for resolution)
+        const pathMatch = findInAttributesMapForPath(
+          cleanedPath,
+          attributesMap,
+          fullToShortPathMap,
+        );
+        if (pathMatch) {
+          return pathMatch;
+        }
+      }
+      // If cleanedPath is null or pathMatch not found, fall through to resolvePathToControllable
+    }
+  }
+
+  // 2. Fall back to resolution via equivalentSignatureVariables
+  const resolution = resolvePathToControllable(
+    localPath,
+    attributesMap,
+    equivalentSignatureVariables,
+    fullToShortPathMap,
+  );
+
+  if (resolution.isControllable && resolution.resolvedPath) {
+    return resolution.resolvedPath;
+  }
+
+  return null;
+}
+
+/**
+ * Converts conditional effects from static analysis into ExecutionFlow objects.
+ *
+ * This allows automatic generation of execution flows based on what the code
+ * actually does, rather than relying on LLM interpretation which may incorrectly
+ * use useState variable names instead of data source conditions.
+ *
+ * IMPORTANT: Only generates flows where ALL condition paths resolve to controllable
+ * data sources. Flows with unresolvable paths (e.g., internal useState variables)
+ * are excluded to prevent invalid mock data.
+ *
+ * @param conditionalEffects - Array of conditional effects from static analysis
+ * @param options - Optional configuration for flow generation
+ * @returns Array of ExecutionFlow objects
+ */
+export default function generateExecutionFlowsFromConditionalEffects(
+  conditionalEffects: ConditionalEffect[],
+  options?: GenerateExecutionFlowsOptions,
+): ExecutionFlow[] {
+  // Use a map to deduplicate flows by ID, keeping the one with MORE conditions
+  // This handles the case where both `condition` (singular) and `conditions` (plural)
+  // entries exist for the same setter - we want the more complete one
+  const flowMap = new Map<string, ExecutionFlow>();
+
+  for (const effect of conditionalEffects) {
+    // Get conditions (handle both single condition and multiple conditions)
+    const conditions: Array<{
+      path: string;
+      conditionType: 'truthiness' | 'comparison' | 'switch';
+      comparedValues?: string[];
+      requiredValue: string | boolean;
+    }> = [];
+
+    if (effect.condition) {
+      conditions.push(effect.condition);
+    } else if (effect.conditions) {
+      conditions.push(...effect.conditions);
+    }
+
+    if (conditions.length === 0) {
+      continue;
+    }
+
+    // Resolve all condition paths to controllable data sources
+    // If ANY path cannot be resolved, skip this entire flow
+    const resolvedConditions: Array<{
+      originalPath: string;
+      resolvedPath: string;
+      conditionType: 'truthiness' | 'comparison' | 'switch';
+      requiredValue: string | boolean;
+    }> = [];
+
+    let allPathsControllable = true;
+    for (const c of conditions) {
+      const resolvedPath = resolveConditionPath(c.path, options);
+      if (!resolvedPath) {
+        // Path is not controllable - skip this entire flow
+        allPathsControllable = false;
+        break;
+      }
+      resolvedConditions.push({
+        originalPath: c.path,
+        resolvedPath,
+        conditionType: c.conditionType,
+        requiredValue: c.requiredValue,
+      });
+    }
+
+    if (!allPathsControllable) {
+      // Skip flows where any condition path cannot be resolved
+      continue;
+    }
+
+    const { stateVariable, value, valueType } = effect.effect;
+
+    // Check if this is a blocking state variable
+    const isBlocking =
+      options?.blocksOtherFlowsMap?.[stateVariable] ??
+      (isBlockingStateVariable(stateVariable) && value === 'true');
+
+    // Generate required values from resolved conditions
+    const requiredValues: ExecutionFlow['requiredValues'] =
+      resolvedConditions.map((c) => ({
+        attributePath: c.resolvedPath,
+        value: getValueString(c.conditionType, c.requiredValue),
+        comparison: getComparisonType(c.conditionType, c.requiredValue),
+        valueType: inferValueType(c.conditionType, c.requiredValue),
+      }));
+
+    // Create the execution flow (use resolved paths in description too)
+    const flowId = generateFlowId(stateVariable, value);
+    const flow: ExecutionFlow = {
+      id: flowId,
+      name: generateFlowName(stateVariable, value, valueType),
+      description: generateFlowDescription(
+        stateVariable,
+        value,
+        valueType,
+        resolvedConditions.map((c) => ({
+          path: c.resolvedPath,
+          requiredValue: c.requiredValue,
+        })),
+      ),
+      requiredValues,
+      impact: determineImpact(valueType, stateVariable),
+      blocksOtherFlows: isBlocking || undefined,
+      sourceLocation: effect.sourceLocation
+        ? {
+            lineNumber: effect.sourceLocation.lineNumber,
+            column: effect.sourceLocation.column,
+          }
+        : undefined,
+      codeSnippet: effect.sourceLocation?.codeSnippet,
+    };
+
+    // Only add/replace if this flow has MORE conditions than existing one
+    // This ensures we keep the most complete condition chain
+    const existingFlow = flowMap.get(flowId);
+    if (
+      !existingFlow ||
+      requiredValues.length > existingFlow.requiredValues.length
+    ) {
+      flowMap.set(flowId, flow);
+    }
+  }
+
+  return Array.from(flowMap.values());
+}
+
+/**
+ * Infer the value type for a condition
+ */
+function inferValueType(
+  conditionType: 'truthiness' | 'comparison' | 'switch',
+  requiredValue: string | boolean,
+): ExecutionFlow['requiredValues'][0]['valueType'] {
+  if (typeof requiredValue === 'boolean') {
+    return 'boolean';
+  }
+
+  // For string values, check if it looks like a number
+  if (!isNaN(Number(requiredValue))) {
+    return 'number';
+  }
+
+  return 'string';
+}