@codeyam/codeyam-cli 0.1.0-staging.8e7b1bd → 0.1.0-staging.b8a55ba

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

@@ -1,11 +1,17 @@
 import completionCall from './completionCall';
 import { saveLlmCall } from '~codeyam/aws/dynamodb';
-import { Analysis, Entity } from '~codeyam/types';
+import type {
+  Analysis,
+  CompoundConditional,
+  ConditionalUsage,
+  Entity,
+} from '~codeyam/types';
 import generateEntityKeyAttributesGenerator from './promptGenerators/generateEntityKeyAttributesGenerator';
 import { awsLog } from '~codeyam/utils';
 import { AI, DEFAULT_LARGER_MODEL } from '~codeyam/ai';
 import isFrontend from './isFrontend';
 import { gatherAttributesMap } from './promptGenerators/gatherAttributesMap';
+import { formatConditionalUsagesForPrompt } from './getConditionalUsagesFromCode';
 
 interface GenerateChangesEntityKeyAttributesArgs {
   entity: Entity;
@@ -41,11 +47,22 @@ export default async function generateChangesEntityKeyAttributes({
       true,
     );
 
+  // Use pre-computed conditional usages from metadata for static analysis context
+  const conditionalUsages: Record<string, ConditionalUsage[]> =
+    isolatedDataStructure?.conditionalUsages ?? {};
+  const compoundConditionals: CompoundConditional[] =
+    isolatedDataStructure?.compoundConditionals ?? [];
+  const staticAnalysisContext = formatConditionalUsagesForPrompt(
+    conditionalUsages,
+    compoundConditionals,
+  );
+
   const prompt = generateEntityKeyAttributesGenerator({
     code: entity.code,
     attributesMap,
     existingKeyAttributes,
     commitDiff,
+    staticAnalysisContext,
   });
 
   const response = await completionCall({

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

@@ -288,7 +288,16 @@ Focus scenario updates on demonstrating this change.${scenarioCount ? ` Generate
 
   return `You are updating data scenarios after a code change. Determine which existing scenarios need updating, which should be removed, and if new ones are needed.
 
-${contextSection}## Update Rules
+${contextSection}## Coverage Goals (IMPORTANT)
+Your primary goal is to MAXIMIZE coverage of key attributes across all scenarios:
+
+1. **Use indexed validValueOptions**: Each key attribute has indexed \`validValueOptions\` (with \`index\` and \`value\`). Reference these by index in your valueOptionRef.
+
+2. **Prioritize attributes with dependencies**: Key attributes with a \`dependencies\` array control conditionally-rendered content. Satisfy these dependencies to reveal gated UI/behavior.
+
+3. **Cover conditional branches**: Use \`codeUsages\` to identify all conditional paths that need coverage.
+
+## Update Rules
 
 ### Removed Key Attributes
 - Update scenarios using removed attributes—replace with new attributes or remove if no longer relevant
@@ -297,6 +306,7 @@ ${contextSection}## Update Rules
 
 ### Added Key Attributes
 - Create or update scenarios to demonstrate new behavior
+- Use different validValueOption indices than existing scenarios to maximize coverage
 
 ### Playwright Instructions
 - Validate existing instructions still work after code changes
@@ -308,7 +318,26 @@ ${contextSection}## Update Rules
 ### Default Scenario
 - First scenario must be "${DEFAULT_SCENARIO_NAME}" (exact name)
 - NEVER include playwrightInstructions—captures initial state only
-- Must include all current key attributes with valid values
+- Must include all current key attributes with valid values from their validValueOptions
+
+## keyAttributeInstructions Format
+Use \`dataStructurePath\` as key. Include variable name, instruction, AND a valueOptionRef that references which validValueOption you're using:
+\`\`\`json
+{
+  "useStatus().status": {
+    "localVariable": "status",
+    "instruction": "Set to 'active' mode",
+    "valueOptionRef": { "index": 0, "refType": "exact" }
+  }
+}
+\`\`\`
+
+### valueOptionRef Types
+- \`"exact"\`: Uses the validValueOption at this index exactly
+- \`"derived"\`: Based on this validValueOption but modified (include \`derivation\` field explaining how)
+- \`"custom"\`: Value not from validValueOptions list (use sparingly)
+
+The \`index\` refers to the validValueOptions array position (0 = first option).
 
 ## Response Format
 
@@ -332,7 +361,11 @@ Otherwise:
       "testName": "it(\\"shows empty message when no notifications\\")",
       "description": "User has no notifications.",
       "keyAttributeInstructions": {
-        "notifications[]": { "localVariable": "notifications[]", "instruction": "Empty array" }
+        "useData().notifications[]": {
+          "localVariable": "notifications[]",
+          "instruction": "Empty array [] to show empty state",
+          "valueOptionRef": { "index": 1, "refType": "exact" }
+        }
       }
     }
   ]
@@ -342,7 +375,7 @@ Otherwise:
 ## Rules
 - Scenario names: letters, numbers, spaces only
 - testName: Jest style with specific expectations
-- Use values from \`validValueOptions\` in key attributes list
+- Use values from \`validValueOptions\` in key attributes list (reference by index)
 - Include dependency key attributes if dependencies involved
 - React elements: simple only (\`<div>\`, \`<span>\`)
 - No external library references—plain JS/TS values

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

@@ -3,6 +3,7 @@ import isolateScopes from './isolateScopes';
 import analyzeScope from './analyzeScope';
 import { FileAnalyzer } from '~codeyam/analyze';
 import { AI, SerializableDataStructure } from '~codeyam/ai';
+import { resetScopeDataStructureMetrics } from './dataStructure/ScopeDataStructure';
 
 // import { awsLog } from '~codeyam/utils';
 
@@ -17,6 +18,10 @@ export default async function generateEntityDataStructure({
   fileAnalyzer,
   model,
 }: GenerateEntityDataStructureArgs): Promise<SerializableDataStructure> {
+  // Reset metrics counters to prevent false "infinite loop" detection when
+  // processing multiple entities in the same run
+  resetScopeDataStructureMetrics();
+
   // awsLog('CodeYam: Generating entity data structure', {
   //   filePath: entity.filePath,
   //   entityName: entity.name,

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

@@ -1,15 +1,16 @@
 import completionCall from './completionCall';
 import { saveLlmCall } from '~codeyam/aws/dynamodb';
-import { DataStructure, Entity } from '~codeyam/types';
+import { DataStructure, Entity, SourceLocation } from '~codeyam/types';
 import generateEntityKeyAttributesGenerator from './promptGenerators/generateEntityKeyAttributesGenerator';
 import { awsLog } from '~codeyam/utils';
 import { DEFAULT_LARGER_MODEL } from './aiConfig';
 import { gatherAttributesMap } from './promptGenerators/gatherAttributesMap';
 import { fillInDirectSchemaGapsAndUnknowns } from './dataStructure/helpers/fillInSchemaGapsAndUnknowns';
+import { clearAttributesFromMapping } from './dataStructure/helpers/cleanNonObjectFunctions';
 import isFrontend from './isFrontend';
 import { AI } from '~codeyam/ai';
 import { formatConditionalUsagesForPrompt } from './getConditionalUsagesFromCode';
-import type { ConditionalUsage } from '~codeyam/types';
+import type { CompoundConditional, ConditionalUsage } from '~codeyam/types';
 
 interface GenerateEntityKeyAttributesArgs {
   entity: Pick<Entity, 'sha' | 'name' | 'filePath' | 'code' | 'metadata'>;
@@ -38,6 +39,11 @@ export default async function generateEntityKeyAttributes({
       true,
     );
 
+  // Clean the attributes map to remove primitive-returning array method paths
+  // like .includes().functionCallReturnValue, .indexOf().functionCallReturnValue, etc.
+  // These paths are not mockable and should not be presented as key attributes.
+  clearAttributesFromMapping(attributesMap);
+
   if (Object.keys(attributesMap).length === 0) {
     console.log(
       `CodeYam Error: No valid attributes found for ${entity.filePath} ${entity.name}`,
@@ -48,17 +54,31 @@ export default async function generateEntityKeyAttributes({
     };
   }
 
+  // Build merged schema for type inference (has more complete nested paths)
+  // Strip signature[N] prefix to match attributesMap format
+  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 (e.g., "unknown | undefined" -> "string | undefined")
+  // Pass mergedSchema so checkIfObjectOrFunction can detect nested paths that prove a type is an object
   const resolvedAttributesMap = fillInDirectSchemaGapsAndUnknowns({
     scopeName: entity.name,
     schema: { ...attributesMap },
+    mergedSchema: mergedSchemaForTypeLookup,
   });
 
   // Use pre-computed conditional usages from metadata, or compute on-the-fly as fallback
   const conditionalUsages: Record<string, ConditionalUsage[]> =
     entity.metadata?.isolatedDataStructure?.conditionalUsages ?? {};
-  const staticAnalysisContext =
-    formatConditionalUsagesForPrompt(conditionalUsages);
+  const compoundConditionals: CompoundConditional[] =
+    entity.metadata?.isolatedDataStructure?.compoundConditionals ?? [];
+  const staticAnalysisContext = formatConditionalUsagesForPrompt(
+    conditionalUsages,
+    compoundConditionals,
+  );
 
   const prompt = generateEntityKeyAttributesGenerator({
     code: entity.code,
@@ -133,6 +153,106 @@ export default async function generateEntityKeyAttributes({
     ]),
   );
 
+  // Helper to extract source locations from conditional usages for a given path
+  const getSourceLocationsForPath = (path: string): SourceLocation[] => {
+    const usages = conditionalUsages[path] || [];
+    const locations: SourceLocation[] = [];
+
+    for (const usage of usages.slice(0, 5)) {
+      // Limit to 5 locations
+      if (usage.sourceLocation) {
+        locations.push({
+          entityName: entity.name,
+          filePath: entity.filePath,
+          lineNumber: usage.sourceLocation.lineNumber,
+          column: usage.sourceLocation.column,
+          codeSnippet: usage.sourceLocation.codeSnippet,
+          usageType: 'conditional',
+          description: `Used in ${usage.location} statement (${usage.conditionType} check)`,
+        });
+      }
+    }
+
+    return locations;
+  };
+
+  // Helper to find source locations by matching sourceDataPath
+  // This handles cases where local variables (e.g., displayState.hasError) trace back
+  // to data structure paths (e.g., getScenarioDisplayState().functionCallReturnValue.hasError)
+  const getSourceLocationsBySourceDataPath = (
+    targetPath: string,
+  ): SourceLocation[] => {
+    const locations: SourceLocation[] = [];
+
+    // Search all conditional usages for ones whose sourceDataPath matches
+    for (const [, usages] of Object.entries(conditionalUsages)) {
+      for (const usage of usages) {
+        const sourceDataPath = (usage as { sourceDataPath?: string })
+          .sourceDataPath;
+        if (!sourceDataPath || !usage.sourceLocation) continue;
+
+        // Check if sourceDataPath ends with the target path
+        // e.g., "LibraryFunctionPreview.signature[0].isOutdated" ends with "isOutdated"
+        // or "getScenarioDisplayState.getScenarioDisplayState(...).functionCallReturnValue.hasError" ends with "hasError"
+        const normalizedSourcePath = sourceDataPath
+          .replace(/\.functionCallReturnValue/g, '')
+          .replace(/\([^)]*\)/g, '()');
+
+        if (
+          normalizedSourcePath.endsWith('.' + targetPath) ||
+          normalizedSourcePath.endsWith('.' + targetPath.replace(/\./g, '.'))
+        ) {
+          locations.push({
+            entityName: entity.name,
+            filePath: entity.filePath,
+            lineNumber: usage.sourceLocation.lineNumber,
+            column: usage.sourceLocation.column,
+            codeSnippet: usage.sourceLocation.codeSnippet,
+            usageType: 'conditional',
+            description: `Used in ${usage.location} statement (${usage.conditionType} check)`,
+          });
+        }
+      }
+    }
+
+    return locations.slice(0, 5); // Limit to 5
+  };
+
+  // Helper to find source locations from LLM-provided code snippets
+  const getSourceLocationsFromSnippets = (
+    codeSnippets: string[] | undefined,
+  ): SourceLocation[] => {
+    if (!codeSnippets || !Array.isArray(codeSnippets)) return [];
+
+    const locations: SourceLocation[] = [];
+    const codeLines = entity.code.split('\n');
+
+    for (const snippet of codeSnippets.slice(0, 3)) {
+      // Limit to 3 snippets
+      if (!snippet || typeof snippet !== 'string') continue;
+
+      // Normalize whitespace for matching
+      const normalizedSnippet = snippet.trim().replace(/\s+/g, ' ');
+
+      for (let i = 0; i < codeLines.length; i++) {
+        const normalizedLine = codeLines[i].replace(/\s+/g, ' ');
+        if (normalizedLine.includes(normalizedSnippet)) {
+          locations.push({
+            entityName: entity.name,
+            filePath: entity.filePath,
+            lineNumber: i + 1, // 1-based line numbers
+            codeSnippet: codeLines[i].trim(),
+            usageType: 'conditional',
+            description: `Key usage identified by analysis`,
+          });
+          break; // Only find first occurrence of each snippet
+        }
+      }
+    }
+
+    return locations;
+  };
+
   const fullKeyAttributes = keyAttributes
     .filter(Boolean)
     .filter(
@@ -144,6 +264,46 @@ export default async function generateEntityKeyAttributes({
     .filter((keyAttribute) => fullPathToInternalPath[keyAttribute.fullPath])
     .map((keyAttribute) => {
       const internalPath = fullPathToInternalPath[keyAttribute.fullPath];
+
+      // Get source locations from conditional usages
+      // Try multiple path formats since conditionalUsages might use different formats:
+      // - internalPath: the short path like "status"
+      // - fullPath: the LLM's path like "signature[0].status"
+      // - dataStructurePath: the external path like "useStatus().status"
+      // - Also try stripping signature[N] prefix since conditional usages use AST paths
+      let sourceLocations = getSourceLocationsForPath(internalPath);
+      if (sourceLocations.length === 0) {
+        sourceLocations = getSourceLocationsForPath(keyAttribute.fullPath);
+      }
+      if (sourceLocations.length === 0) {
+        const dataStructurePath =
+          dataStructurePathMap[internalPath] || keyAttribute.fullPath;
+        sourceLocations = getSourceLocationsForPath(dataStructurePath);
+      }
+      // Also try the path without signature[N] prefix since AST uses local variable names
+      if (sourceLocations.length === 0) {
+        const pathWithoutSignature = internalPath.replace(
+          /^signature\[\d+\]\./,
+          '',
+        );
+        if (pathWithoutSignature !== internalPath) {
+          sourceLocations = getSourceLocationsForPath(pathWithoutSignature);
+        }
+      }
+      // Finally, search by sourceDataPath which traces local variables back to data sources
+      // This handles cases like displayState.hasError → getScenarioDisplayState().hasError
+      if (sourceLocations.length === 0) {
+        sourceLocations = getSourceLocationsBySourceDataPath(internalPath);
+      }
+
+      // Last resort: use LLM-provided code snippets to find source locations
+      // This ensures every key attribute the LLM identifies has a source location
+      if (sourceLocations.length === 0 && keyAttribute.codeSnippets) {
+        sourceLocations = getSourceLocationsFromSnippets(
+          keyAttribute.codeSnippets,
+        );
+      }
+
       return {
         internalPath,
         externalPath: associationMap[internalPath],
@@ -155,6 +315,9 @@ export default async function generateEntityKeyAttributes({
         // Preserve new fields from LLM response
         valueType: keyAttribute.valueType,
         dependencies: keyAttribute.dependencies,
+        // Add source locations from static analysis or LLM snippets
+        sourceLocations:
+          sourceLocations.length > 0 ? sourceLocations : undefined,
       };
     });
 
@@ -184,15 +347,31 @@ NOT key attributes:
 
 We've provided a list of variables that are used in conditional statements in the code. These are very likely key attributes.
 
-Each conditional lists it's source and how it is used. This should help you identify which attributes to include and what values to suggest.
+Each conditional lists its source and how it is used. This should help you identify which attributes to include and what values to suggest.
+
+**IMPORTANT**: Only include attributes with explicit evidence of impact in THIS code:
+- Used directly in a conditional statement (if/ternary/switch)
+- Displayed or rendered directly (e.g., text content, list length)
+- Used in a computation that affects rendering
+
+Do NOT include attributes that are only passed as arguments to other functions without direct usage here. We analyze those functions separately and merge their key attributes automatically.
 
 ## Path Format
 
 Only return attributes from the "Attributes and Value Types" list — these are the only values we can control. Use the exact \`fullPath\` provided. Use \`functionCallReturnValue\` for function return values. Use \`[]\` for array items (e.g., \`items[]\`).
 
-## Dependencies
+## Dependencies and Compound Conditionals
+
+When attributes are used in && chains (compound conditionals), they form dependencies on each other:
+- Each attribute in the chain only has effect when ALL other conditions in the chain are satisfied
+- Include these as dependencies with the required value for the code path to execute
 
-If this key attribute is only used if one or more other attributes have specific values, include those dependencies in a \`dependencies\` array.
+Example: For \`a && b && !c\`:
+- \`a\` has dependencies: \`b\` must be truthy, \`c\` must be falsy
+- \`b\` has dependencies: \`a\` must be truthy, \`c\` must be falsy
+- \`c\` has dependencies: \`a\` must be truthy, \`b\` must be truthy (for the falsy check to matter)
+
+The static analysis section may show "Compound Conditionals" that list which conditions must be true together. Use this to populate the \`dependencies\` array with \`{ "path": "...", "requiredValue": "..." }\` entries.
 
 ## Value Type
 
@@ -218,8 +397,9 @@ List all key attributes in order from most impactful to least impactful regardin
     {
       "fullPath": "signature[0].user",
       "description": "Controls whether the main form or redirect screen displays",
+      "codeSnippets": ["if (!user) return <Redirect />", "user.name"],
       "dependencies": [
-        "signature[0].projectId": "must be a valid project ID for 'user' to have effect"
+        { "path": "signature[0].projectId", "requiredValue": "truthy", "description": "must be a valid project ID for 'user' to have effect" }
       ],
       "valueType": "object",
       "validValueOptions": ["an empty object {}", "null/undefined"]
@@ -227,6 +407,8 @@ List all key attributes in order from most impactful to least impactful regardin
   ]
 }
 \`\`\`
+
+The \`codeSnippets\` field is required - provide 1-3 short code excerpts (under 80 chars each) showing exactly where and how this attribute is used. These snippets must appear verbatim in the code.
 `;
 
 const BACKEND_SYSTEM_MESSAGE = `You analyze backend functions to identify key data attributes that significantly impact behavior.
@@ -248,15 +430,31 @@ NOT key attributes:
 
 We've provided a list of variables that are used in conditional statements in the code. These are very likely key attributes.
 
-Each conditional lists it's source and how it is used. This should help you identify which attributes to include and what values to suggest.
+Each conditional lists its source and how it is used. This should help you identify which attributes to include and what values to suggest.
+
+**IMPORTANT**: Only include attributes with explicit evidence of impact in THIS code:
+- Used directly in a conditional statement (if/ternary/switch)
+- Displayed or rendered directly (e.g., text content, list length)
+- Used in a computation that affects rendering
+
+Do NOT include attributes that are only passed as arguments to other functions without direct usage here. We analyze those functions separately and merge their key attributes automatically.
 
 ## Path Format
 
 Only return attributes from the "Attributes and Value Types" list — these are the only values we can control. Use the exact \`fullPath\` provided. Use \`functionCallReturnValue\` for function return values. Use \`[]\` for array items (e.g., \`items[]\`).
 
-## Dependencies
+## Dependencies and Compound Conditionals
 
-If this key attribute is only used if one or more other attributes have specific values, include those dependencies in a \`dependencies\` array.
+When attributes are used in && chains (compound conditionals), they form dependencies on each other:
+- Each attribute in the chain only has effect when ALL other conditions in the chain are satisfied
+- Include these as dependencies with the required value for the code path to execute
+
+Example: For \`a && b && !c\`:
+- \`a\` has dependencies: \`b\` must be truthy, \`c\` must be falsy
+- \`b\` has dependencies: \`a\` must be truthy, \`c\` must be falsy
+- \`c\` has dependencies: \`a\` must be truthy, \`b\` must be truthy (for the falsy check to matter)
+
+The static analysis section may show "Compound Conditionals" that list which conditions must be true together. Use this to populate the \`dependencies\` array with \`{ "path": "...", "requiredValue": "..." }\` entries.
 
 ## Value Type
 
@@ -282,8 +480,9 @@ List all key attributes in order from most impactful to least impactful using th
     {
       "fullPath": "signature[0].config.enabled",
       "description": "Controls whether the main processing logic runs",
+      "codeSnippets": ["if (!config.enabled) return", "enabled && processData()"],
       "dependencies": [
-        "signature[0].analysisMode": "must be 'full' for 'enabled' to have effect"
+        { "path": "signature[0].analysisMode", "requiredValue": "full", "description": "must be 'full' for 'enabled' to have effect" }
       ],
       "valueType": "boolean",
       "validValueOptions": ["true", "false"]
@@ -291,4 +490,6 @@ List all key attributes in order from most impactful to least impactful using th
   ]
 }
 \`\`\`
+
+The \`codeSnippets\` field is required - provide 1-3 short code excerpts (under 80 chars each) showing exactly where and how this attribute is used. These snippets must appear verbatim in the code.
 `;

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

@@ -318,29 +318,25 @@ Use for relative dates. Code runs in Node (no browser APIs, no external librarie
 Use simple elements only (\`<div>\`, \`<span>\`). No custom components.
 
 ## Mock Data Keys
-Preserve keys exactly as written in the structure. There are two formats:
+**CRITICAL: Use keys EXACTLY as provided in the structure. Do NOT change key formats.**
 
-### Standard function calls
+Keys use the canonical format: \`EntityName::hookName::index\`
 \`\`\`json
 {
   "mockData": {
-    "useUser()": { "user": { "name": "John" } },
-    "from().select()": [{ "id": "1" }]
+    "DashboardPage::useLoaderData::0": { "user": { "name": "John" } },
+    "DashboardPage::useFetcher::0": { "data": null, "state": "idle" },
+    "DashboardPage::useFetcher::1": { "data": { "reportId": "abc123" } }
   }
 }
 \`\`\`
 
-### Variable-qualified calls (for multiple calls to the same function)
-When the same function is called multiple times with results stored in different variables, keys use the format \`variableName <- functionName\`:
-\`\`\`json
-{
-  "mockData": {
-    "entityDiffFetcher <- useFetcher": { "data": null, "state": "idle" },
-    "reportFetcher <- useFetcher": { "data": { "reportId": "abc123" }, "state": "idle" }
-  }
-}
-\`\`\`
-This reads as "entityDiffFetcher receives from useFetcher". Each variable gets its own distinct mock data.
+The format is deterministic:
+- \`EntityName\` - the component name
+- \`hookName\` - the function/hook being called
+- \`index\` - distinguishes multiple calls to the same hook (0, 1, 2...)
+
+**You MUST use the exact keys provided in the structure. Do NOT substitute variable names or use alternative formats.**
 
 ## Response Format
 \`\`\`json