@codeyam/codeyam-cli 0.1.0-staging.596f0eb → 0.1.0-staging.6e699e5

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

@@ -218,7 +218,11 @@ export function joinParenthesesAndArrays(parts: string[]): string {
 
   const noIndexParts: string[] = [];
   for (const part of parts) {
-    if (noIndexParts.length > 0 && part.startsWith('[')) {
+    // Append array indices [x] and function call arguments (x) directly without a dot
+    if (
+      noIndexParts.length > 0 &&
+      (part.startsWith('[') || part.startsWith('('))
+    ) {
       noIndexParts[noIndexParts.length - 1] += part;
     } else {
       noIndexParts.push(part);

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

@@ -0,0 +1,531 @@
+import type { ExecutionFlow } from '~codeyam/types';
+
+/**
+ * Classification types for execution flow paths
+ */
+export type PathClassification =
+  | 'controllable'
+  | 'needs_resolution'
+  | 'interaction_required';
+
+/**
+ * Result of classifying a single path
+ */
+export interface PathClassificationResult {
+  classification: PathClassification;
+  originalPath: string;
+  dataSourcePath?: string;
+}
+
+/**
+ * Result of classifying an entire execution flow
+ */
+export interface FlowClassificationResult {
+  classification: PathClassification;
+  controllablePaths: string[];
+  unresolvedPaths: string[];
+}
+
+/**
+ * Result of attempting to resolve execution flow paths
+ */
+export interface FlowResolutionResult {
+  resolved: boolean;
+  classification: PathClassification;
+  flow: ExecutionFlow;
+  resolvedPaths: string[];
+  unresolvedPaths: string[];
+  interactionRequiredPaths: string[];
+}
+
+/**
+ * Result of processing all execution flows
+ */
+export interface ProcessExecutionFlowsResult {
+  controllableFlows: ExecutionFlow[];
+  interactionRequiredFlows: ExecutionFlow[];
+  needsLlmResolution: ExecutionFlow[];
+}
+
+/**
+ * Classify a single attribute path.
+ *
+ * @param path - The attribute path from an execution flow
+ * @param attributesMap - Map of controllable paths to their types
+ * @param fullToShortPathMap - Optional map from full paths to short paths (for hook paths)
+ * @returns Classification result
+ */
+export function classifyExecutionFlowPath(
+  path: string,
+  attributesMap: Record<string, string>,
+  fullToShortPathMap?: Record<string, string>,
+): PathClassificationResult {
+  // Check if path exists directly in attributesMap
+  if (path in attributesMap) {
+    return {
+      classification: 'controllable',
+      originalPath: path,
+      dataSourcePath: path,
+    };
+  }
+
+  // Check if this is a sub-path of a controllable path
+  // e.g., "props.data.items[0].name" might match "props.data.items[].name"
+  const normalizedPath = path.replace(/\[\d+\]/g, '[]');
+  if (normalizedPath in attributesMap) {
+    return {
+      classification: 'controllable',
+      originalPath: path,
+      dataSourcePath: normalizedPath,
+    };
+  }
+
+  // Try to convert full path to short path using the association map
+  // e.g., "useLoaderData<LoaderData>().functionCallReturnValue.entity.sha" → "entity.sha"
+  if (fullToShortPathMap && path in fullToShortPathMap) {
+    const shortPath = fullToShortPathMap[path];
+    if (shortPath in attributesMap) {
+      return {
+        classification: 'controllable',
+        originalPath: path,
+        dataSourcePath: shortPath,
+      };
+    }
+  }
+
+  // Path doesn't exist in attributesMap - needs resolution
+  return {
+    classification: 'needs_resolution',
+    originalPath: path,
+  };
+}
+
+/**
+ * Extended ExecutionFlow type that may have interactionRequired marker
+ */
+type ExecutionFlowWithInteraction = ExecutionFlow & {
+  interactionRequired?: boolean;
+};
+
+/**
+ * Classify an entire execution flow based on its requiredValues paths.
+ *
+ * @param flow - The execution flow to classify
+ * @param attributesMap - Map of controllable paths to their types
+ * @param fullToShortPathMap - Optional map from full paths to short paths (for hook paths)
+ * @returns Classification result for the flow
+ */
+export function classifyExecutionFlow(
+  flow: ExecutionFlowWithInteraction,
+  attributesMap: Record<string, string>,
+  fullToShortPathMap?: Record<string, string>,
+): FlowClassificationResult {
+  // If already marked as interaction-required by LLM, respect that
+  if (flow.interactionRequired) {
+    return {
+      classification: 'interaction_required',
+      controllablePaths: [],
+      unresolvedPaths: flow.requiredValues.map((rv) => rv.attributePath),
+    };
+  }
+
+  const controllablePaths: string[] = [];
+  const unresolvedPaths: string[] = [];
+
+  for (const rv of flow.requiredValues) {
+    const result = classifyExecutionFlowPath(
+      rv.attributePath,
+      attributesMap,
+      fullToShortPathMap,
+    );
+    if (result.classification === 'controllable') {
+      controllablePaths.push(rv.attributePath);
+    } else {
+      unresolvedPaths.push(rv.attributePath);
+    }
+  }
+
+  // If any path is unresolved, the whole flow needs resolution
+  if (unresolvedPaths.length > 0) {
+    return {
+      classification: 'needs_resolution',
+      controllablePaths,
+      unresolvedPaths,
+    };
+  }
+
+  return {
+    classification: 'controllable',
+    controllablePaths,
+    unresolvedPaths: [],
+  };
+}
+
+/**
+ * Extract the local variable name from a path like "ComponentName.variableName"
+ * or just "variableName"
+ */
+function extractLocalVariableName(path: string): string {
+  // Handle "Component.stateName" pattern - extract just the state name
+  const parts = path.split('.');
+  if (parts.length >= 2) {
+    // Check if first part looks like a component name (PascalCase)
+    const firstPart = parts[0];
+    if (/^[A-Z][a-zA-Z0-9]*$/.test(firstPart)) {
+      // Return the second part as the variable name
+      return parts[1];
+    }
+  }
+  // Otherwise return the first part
+  return parts[0];
+}
+
+/**
+ * Resolve a compound path by replacing the local variable with its data source.
+ *
+ * When the data source is a function call (ends with `()`), we need to insert
+ * `.functionCallReturnValue.` to match how paths are stored in the data structure.
+ *
+ * Examples:
+ * - resolveCompoundPath("debugFetcher.state", "debugFetcher", "useFetcher<...>()")
+ *   → "useFetcher<...>().functionCallReturnValue.state"
+ * - resolveCompoundPath("debugFetcher.data.success", "debugFetcher", "useFetcher<...>()")
+ *   → "useFetcher<...>().functionCallReturnValue.data.success"
+ * - resolveCompoundPath("EntityDetail.showDebugModal", "showDebugModal", "useFetcher<...>().data.success")
+ *   → "useFetcher<...>().data.success" (no suffix in this case, data source already has path)
+ */
+function resolveCompoundPath(
+  originalPath: string,
+  localVarName: string,
+  dataSourceBase: string,
+): string {
+  // Find where the local variable appears in the path
+  const varIndex = originalPath.indexOf(localVarName);
+  if (varIndex === -1) {
+    // Shouldn't happen, but return the data source as fallback
+    return dataSourceBase;
+  }
+
+  // Get the suffix after the local variable name (e.g., ".data.success" from "debugFetcher.data.success")
+  const afterVar = originalPath.slice(varIndex + localVarName.length);
+
+  // If there's no suffix, just return the data source
+  if (!afterVar || afterVar === '') {
+    return dataSourceBase;
+  }
+
+  // If the data source is a function call (ends with `()`), we need to insert
+  // `.functionCallReturnValue` before the property access because that's how
+  // the data structure paths are stored.
+  // e.g., "debugFetcher.data" with dataSource "useFetcher<...>()"
+  // becomes "useFetcher<...>().functionCallReturnValue.data"
+  if (dataSourceBase.endsWith('()')) {
+    return dataSourceBase + '.functionCallReturnValue' + afterVar;
+  }
+
+  // Otherwise just combine them directly
+  return dataSourceBase + afterVar;
+}
+
+/**
+ * Attempt to resolve execution flow paths to their data sources.
+ * Uses equivalentVariables mapping to trace local variables back to data sources.
+ *
+ * @param flow - The execution flow to resolve
+ * @param attributesMap - Map of controllable paths to their types
+ * @param equivalentVariables - Map from local variable names to their data source paths
+ * @param fullToShortPathMap - Optional map from full paths to short paths (for hook paths)
+ * @returns Resolution result
+ */
+export function resolveExecutionFlowPaths(
+  flow: ExecutionFlow,
+  attributesMap: Record<string, string>,
+  equivalentVariables: Record<string, string>,
+  fullToShortPathMap?: Record<string, string>,
+): FlowResolutionResult {
+  const resolvedPaths: string[] = [];
+  const unresolvedPaths: string[] = [];
+  const interactionRequiredPaths: string[] = [];
+
+  // Deep clone the flow to avoid mutating the original
+  const resolvedFlow: ExecutionFlow = JSON.parse(JSON.stringify(flow));
+
+  for (let i = 0; i < resolvedFlow.requiredValues.length; i++) {
+    const rv = resolvedFlow.requiredValues[i];
+    const pathResult = classifyExecutionFlowPath(
+      rv.attributePath,
+      attributesMap,
+      fullToShortPathMap,
+    );
+
+    if (pathResult.classification === 'controllable') {
+      // Path is already controllable
+      resolvedPaths.push(rv.attributePath);
+      continue;
+    }
+
+    // Try to resolve using equivalentVariables
+    const localVarName = extractLocalVariableName(rv.attributePath);
+    const dataSourceBase = equivalentVariables[localVarName];
+
+    if (dataSourceBase) {
+      // Build the full resolved path by replacing the local variable with its data source
+      // e.g., "debugFetcher.state" with dataSourceBase "useFetcher<...>()"
+      // becomes "useFetcher<...>().functionCallReturnValue.state"
+      const fullResolvedPath = resolveCompoundPath(
+        rv.attributePath,
+        localVarName,
+        dataSourceBase,
+      );
+
+      console.log('CodeYam: Attempting path resolution', {
+        originalPath: rv.attributePath,
+        localVarName,
+        dataSourceBase: dataSourceBase.slice(0, 60) + '...',
+        resolvedPath: fullResolvedPath.slice(0, 80) + '...',
+      });
+
+      // Check if the full resolved path is in attributesMap
+      const resolvedPathResult = classifyExecutionFlowPath(
+        fullResolvedPath,
+        attributesMap,
+        fullToShortPathMap,
+      );
+
+      console.log('CodeYam: Path resolution result', {
+        resolvedPath: fullResolvedPath.slice(0, 80) + '...',
+        classification: resolvedPathResult.classification,
+        dataSourcePath: resolvedPathResult.dataSourcePath,
+        inFullToShortMap: fullToShortPathMap
+          ? fullResolvedPath in fullToShortPathMap
+          : 'no map',
+      });
+
+      if (resolvedPathResult.classification === 'controllable') {
+        // Successfully resolved!
+        resolvedFlow.requiredValues[i] = {
+          ...rv,
+          attributePath: fullResolvedPath,
+        };
+        resolvedPaths.push(fullResolvedPath);
+        continue;
+      }
+    }
+
+    // Could not resolve - check if we have evidence it's interaction-required
+    // We only mark as interaction_required if we looked up the variable and it
+    // explicitly wasn't in equivalentVariables (meaning the static analysis
+    // determined it has no data source). If equivalentVariables is empty/sparse,
+    // we flag for LLM resolution instead.
+    const hasEquivalentVariables = Object.keys(equivalentVariables).length > 0;
+    const variableWasLookedUp =
+      localVarName in equivalentVariables || hasEquivalentVariables;
+
+    if (variableWasLookedUp && !(localVarName in equivalentVariables)) {
+      // We have mappings but this variable isn't in them - likely interaction-required
+      interactionRequiredPaths.push(rv.attributePath);
+    }
+
+    unresolvedPaths.push(rv.attributePath);
+  }
+
+  // Determine overall classification
+  let classification: PathClassification;
+  const allResolved = unresolvedPaths.length === 0;
+
+  if (allResolved) {
+    classification = 'controllable';
+  } else if (
+    interactionRequiredPaths.length === unresolvedPaths.length &&
+    interactionRequiredPaths.length > 0
+  ) {
+    // All unresolved paths were determined to be interaction-required
+    classification = 'interaction_required';
+  } else {
+    // Some paths couldn't be resolved and we don't know if they're interaction-required
+    classification = 'needs_resolution';
+  }
+
+  return {
+    resolved: allResolved,
+    classification,
+    flow: resolvedFlow,
+    resolvedPaths,
+    unresolvedPaths,
+    interactionRequiredPaths,
+  };
+}
+
+/**
+ * Generate a prompt for the LLM to resolve unresolved execution flow paths.
+ *
+ * @param unresolvedFlows - Flows with paths that couldn't be auto-resolved
+ * @param attributesMap - Map of controllable paths to their types
+ * @returns Prompt string for LLM
+ */
+export function generatePathResolutionPrompt(
+  unresolvedFlows: ExecutionFlow[],
+  attributesMap: Record<string, string>,
+): string {
+  const availablePaths = Object.entries(attributesMap)
+    .map(([path, type]) => `- ${path}: ${type}`)
+    .join('\n');
+
+  const flowsToResolve = unresolvedFlows
+    .map((flow) => {
+      const unresolvedPaths = flow.requiredValues
+        .filter((rv) => !(rv.attributePath in attributesMap))
+        .map((rv) => rv.attributePath);
+
+      return `Flow "${flow.name}" (${flow.id}):
+  Unresolved paths:
+${unresolvedPaths.map((p) => `    - ${p}`).join('\n')}`;
+    })
+    .join('\n\n');
+
+  return `## Execution Flow Path Resolution Required
+
+The following execution flows have attribute paths that don't map to controllable data sources.
+For each unresolved path, either:
+1. Map it to a data source from the available paths below
+2. Mark the flow as \`interactionRequired: true\` if it can only be triggered by user interaction (clicking a button, etc.)
+
+### Available Data Sources (controllable via mock data)
+${availablePaths}
+
+### Flows Needing Resolution
+${flowsToResolve}
+
+### Response Format
+Return a JSON object with resolved flows:
+\`\`\`json
+{
+  "resolvedFlows": [
+    {
+      "id": "flow-id",
+      "resolvedPaths": {
+        "OriginalPath.name": "mappedDataSource.path"
+      },
+      "interactionRequired": false
+    }
+  ]
+}
+\`\`\`
+
+If a path cannot be mapped to a data source and requires user interaction, set \`interactionRequired: true\`.
+`;
+}
+
+/**
+ * Process all execution flows: classify, resolve, and categorize.
+ *
+ * @param executionFlows - All execution flows to process
+ * @param attributesMap - Map of controllable paths to their types
+ * @param equivalentVariables - Map from local variable names to their data source paths
+ * @param fullToShortPathMap - Optional map from full paths to short paths (for hook paths)
+ * @returns Categorized flows
+ */
+export function processExecutionFlows(
+  executionFlows: ExecutionFlow[],
+  attributesMap: Record<string, string>,
+  equivalentVariables: Record<string, string>,
+  fullToShortPathMap?: Record<string, string>,
+): ProcessExecutionFlowsResult {
+  // Log a sample of available mappings for debugging
+  const sampleFullToShort = fullToShortPathMap
+    ? Object.entries(fullToShortPathMap)
+        .filter(([k]) => k.includes('Fetcher') || k.includes('success'))
+        .slice(0, 5)
+        .map(([k, v]) => `${k.slice(0, 60)}... -> ${v}`)
+    : [];
+  const sampleEquivalent = Object.entries(equivalentVariables)
+    .filter(([k]) => k.includes('Fetcher') || k.includes('fetcher'))
+    .slice(0, 5)
+    .map(([k, v]) => `${k} -> ${v.slice(0, 50)}...`);
+
+  console.log('CodeYam: processExecutionFlows starting', {
+    totalFlows: executionFlows.length,
+    attributesMapSize: Object.keys(attributesMap).length,
+    equivalentVariablesSize: Object.keys(equivalentVariables).length,
+    fullToShortMapSize: fullToShortPathMap
+      ? Object.keys(fullToShortPathMap).length
+      : 0,
+    sampleFullToShort,
+    sampleEquivalent,
+  });
+
+  const controllableFlows: ExecutionFlow[] = [];
+  const interactionRequiredFlows: ExecutionFlow[] = [];
+  const needsLlmResolution: ExecutionFlow[] = [];
+
+  for (const flow of executionFlows) {
+    // First classify
+    const classification = classifyExecutionFlow(
+      flow,
+      attributesMap,
+      fullToShortPathMap,
+    );
+
+    if (classification.classification === 'controllable') {
+      // Already controllable, no resolution needed
+      controllableFlows.push(flow);
+      continue;
+    }
+
+    if (classification.classification === 'interaction_required') {
+      // Already marked as interaction required
+      interactionRequiredFlows.push(flow);
+      continue;
+    }
+
+    // Try to resolve
+    const resolution = resolveExecutionFlowPaths(
+      flow,
+      attributesMap,
+      equivalentVariables,
+      fullToShortPathMap,
+    );
+
+    if (resolution.resolved) {
+      // Successfully resolved all paths
+      controllableFlows.push(resolution.flow);
+      console.log(`CodeYam: Resolved execution flow "${flow.name}" paths`, {
+        originalPaths: flow.requiredValues.map((rv) => rv.attributePath),
+        resolvedPaths: resolution.flow.requiredValues.map(
+          (rv) => rv.attributePath,
+        ),
+      });
+    } else if (resolution.classification === 'interaction_required') {
+      // Some paths require user interaction
+      interactionRequiredFlows.push(flow);
+      console.log(
+        `CodeYam: Execution flow "${flow.name}" requires user interaction`,
+        {
+          interactionRequiredPaths: resolution.interactionRequiredPaths,
+        },
+      );
+    } else {
+      // Could not resolve - needs LLM help
+      needsLlmResolution.push(flow);
+      console.log(
+        `CodeYam: Execution flow "${flow.name}" needs LLM resolution`,
+        {
+          unresolvedPaths: resolution.unresolvedPaths,
+        },
+      );
+    }
+  }
+
+  // Log summary
+  console.log('CodeYam: Filtered out execution flows with unresolvable paths', {
+    controllable: controllableFlows.length,
+    interactionRequired: interactionRequiredFlows.length,
+    needsLlmResolution: needsLlmResolution.length,
+  });
+
+  return {
+    controllableFlows,
+    interactionRequiredFlows,
+    needsLlmResolution,
+  };
+}

package/analyzer-template/packages/ai/src/lib/worker/SerializableDataStructure.ts

@@ -10,6 +10,11 @@ import {
   fuzzyMatchFunctionName,
   findFuzzyMatchingKey,
 } from './fuzzyMatchFunctionName';
+import type {
+  ConditionalEffect,
+  CompoundConditional,
+  JsxRenderingUsage,
+} from '../astScopes/types';
 
 export interface SerializableScopeVariable {
   scopeNodeName: string;
@@ -28,6 +33,11 @@ export interface SerializableFunctionCallInfo {
   receivingVariableNames?: string[];
   /** Maps each call signature to the variable that receives its return value */
   callSignatureToVariable?: Record<string, string>;
+  /**
+   * Stores individual return value schemas per receiving variable, BEFORE merging.
+   * Key is the receiving variable name (e.g., "userFetcher", "reportFetcher").
+   */
+  perVariableSchemas?: Record<string, Record<string, string>>;
 }
 
 export interface SerializableFunctionResult {
@@ -60,6 +70,43 @@ export interface EnrichedConditionalUsage {
    * This connects the local variable to the original data attribute.
    */
   sourceDataPath?: string;
+  /** Whether this condition is negated (e.g., !foo) */
+  isNegated?: boolean;
+  /**
+   * Whether this conditional controls JSX rendering.
+   * True when the conditional appears in a JSX expression like {cond && <Component />}
+   */
+  controlsJsxRendering?: boolean;
+  /** Source location information */
+  sourceLocation?: {
+    lineNumber: number;
+    column: number;
+    codeSnippet: string;
+  };
+  /**
+   * Information about how this variable was derived from other variables.
+   * Used to trace derived boolean variables back to their data sources.
+   */
+  derivedFrom?: {
+    /** For single-source derivations (notNull, equals, etc.) */
+    sourcePath?: string;
+    /** For multi-source derivations (or, and) */
+    sourcePaths?: string[];
+    /** The operation that derived this variable */
+    operation:
+      | 'notNull'
+      | 'isNull'
+      | 'equals'
+      | 'notEquals'
+      | 'or'
+      | 'and'
+      | 'arrayIncludes'
+      | 'arraySome'
+      | 'arrayEvery'
+      | 'arrayLength';
+    /** For comparison operations, the value being compared to */
+    comparedValue?: string;
+  };
 }
 
 export interface SerializableDataStructure {
@@ -83,6 +130,41 @@ export interface SerializableDataStructure {
    * the traced source data path.
    */
   conditionalUsages?: Record<string, EnrichedConditionalUsage[]>;
+
+  /**
+   * Conditional effects tracking.
+   * Tracks what setter calls happen inside conditionals (if, switch, ternary).
+   * Used to auto-generate execution flows from static analysis.
+   */
+  conditionalEffects?: ConditionalEffect[];
+
+  /**
+   * Compound conditionals grouped by chain (all conditions must be true together).
+   * Used to generate execution flows that satisfy ALL conditions in compound expressions like:
+   *   (hasNewerVersion || isFromDifferentVersion) && !isAnalyzing && !isQueued
+   */
+  compoundConditionals?: CompoundConditional[];
+
+  /**
+   * Gating conditions for child component boundaries.
+   * Maps child component name to the conditions that must be true for that child to render.
+   *
+   * Example:
+   * {hasAnalysis && <ScenarioViewer />} would produce:
+   * { ScenarioViewer: [{ path: 'hasAnalysis', conditionType: 'truthiness', ... }] }
+   *
+   * This allows us to merge child component execution flows with parent gating conditions.
+   */
+  childBoundaryGatingConditions?: Record<string, EnrichedConditionalUsage[]>;
+
+  /**
+   * JSX rendering usages - tracks arrays rendered via .map() and strings interpolated in JSX.
+   * Used to generate execution flows for array sizes and text lengths without explicit conditionals.
+   *
+   * Example:
+   * {items.map(i => <Item {...i} />)} produces an array-map usage for 'items'
+   */
+  jsxRenderingUsages?: JsxRenderingUsage[];
 }
 
 /**
@@ -227,3 +309,44 @@ export function getConditionalUsages(
 ): Record<string, EnrichedConditionalUsage[]> {
   return dataStructure.conditionalUsages ?? {};
 }
+
+/**
+ * Get conditional effects (setter calls inside conditionals).
+ * Returns the array of conditional effects, or empty array if not available.
+ */
+export function getConditionalEffects(
+  dataStructure: SerializableDataStructure,
+): ConditionalEffect[] {
+  return dataStructure.conditionalEffects ?? [];
+}
+
+/**
+ * Get compound conditionals (grouped conditions that must all be true).
+ * Returns the array of compound conditionals, or empty array if not available.
+ */
+export function getCompoundConditionals(
+  dataStructure: SerializableDataStructure,
+): CompoundConditional[] {
+  return dataStructure.compoundConditionals ?? [];
+}
+
+/**
+ * Get child boundary gating conditions.
+ * Returns the mapping of child component names to their gating conditions,
+ * or empty object if not available.
+ */
+export function getChildBoundaryGatingConditions(
+  dataStructure: SerializableDataStructure,
+): Record<string, EnrichedConditionalUsage[]> {
+  return dataStructure.childBoundaryGatingConditions ?? {};
+}
+
+/**
+ * Get JSX rendering usages (arrays rendered via .map() and strings interpolated in JSX).
+ * Returns the array of JSX rendering usages, or empty array if not available.
+ */
+export function getJsxRenderingUsages(
+  dataStructure: SerializableDataStructure,
+): JsxRenderingUsage[] {
+  return dataStructure.jsxRenderingUsages ?? [];
+}