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

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

@@ -1,23 +1,26 @@
 import completionCall from './completionCall';
 import { saveLlmCall } from '~codeyam/aws/dynamodb';
-import { 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'>;
+  mergedDataStructure: Omit<DataStructure, 'equivalentSignatureVariables'>;
   model?: AI.Model;
 }
 
 export default async function generateEntityKeyAttributes({
   entity,
+  mergedDataStructure,
   model,
 }: GenerateEntityKeyAttributesArgs) {
   awsLog(`CodeYam: Generating entity key attributes`, {
@@ -25,8 +28,21 @@ export default async function generateEntityKeyAttributes({
     entityName: entity.name,
   });
 
+  const isolatedDataStructure = entity.metadata?.isolatedDataStructure;
+  const equivalentSignatureVariables =
+    isolatedDataStructure?.equivalentSignatureVariables ?? {};
   const { attributesMap, associationMap, dataStructurePathMap } =
-    gatherAttributesMap(entity, true);
+    gatherAttributesMap(
+      isolatedDataStructure ?? mergedDataStructure,
+      mergedDataStructure,
+      equivalentSignatureVariables,
+      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(
@@ -38,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,
@@ -123,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(
@@ -134,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],
@@ -142,6 +312,12 @@ export default async function generateEntityKeyAttributes({
         description: keyAttribute.description,
         validValueOptions: keyAttribute.validValueOptions,
         errorValueOptions: keyAttribute.errorValueOptions,
+        // 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,
       };
     });
 
@@ -171,15 +347,42 @@ 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 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
+
+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
+
+Should reiterate the type of the attribute (e.g., "string", "object", "array", "boolean", etc.) based on the "Attributes and Value Types" list.
+
+All validValueOptions must be of this type.
+
 ## Valid Value Options
 
-- For \`validValueOptions\`, include boundary/extreme values that trigger different behavior 
+- For \`validValueOptions\`, include boundary/extreme values that trigger different behavior
+- Each of the \`validValueOptions\` must be the exact type that we provide in "Attributes and Value Types".
 - Be very specific with values. Do not make them ambiguous in any way
 — Do NOT include values that would cause unexpected/unhandled errors.
 - Ensure all values or value ranges that will trigger different rendering behavior are included
@@ -194,11 +397,18 @@ 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": [
+        { "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"]
     }
   ]
 }
 \`\`\`
+
+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.
@@ -220,15 +430,42 @@ 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 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
+
+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
+
+Should reiterate the type of the attribute (e.g., "string", "object", "array", "boolean", etc.) based on the "Attributes and Value Types" list.
+
+All validValueOptions must be of this type.
+
 ## Valid Value Options
 
-- For \`validValueOptions\`, include boundary/extreme values that trigger different behavior 
+- For \`validValueOptions\`, include boundary/extreme values that trigger different behavior
+- Each of the \`validValueOptions\` must be the exact type that we provide in "Attributes and Value Types".
 - Be very specific with values. Do not make them ambiguous in any way
 — Do NOT include values that would cause unexpected/unhandled errors.
 - Ensure all values or value ranges that will trigger different rendering behavior are included
@@ -243,9 +480,16 @@ 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": [
+        { "path": "signature[0].analysisMode", "requiredValue": "full", "description": "must be 'full' for 'enabled' to have effect" }
+      ],
+      "valueType": "boolean",
       "validValueOptions": ["true", "false"]
     }
   ]
 }
 \`\`\`
+
+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

@@ -11,6 +11,7 @@ import type {
 import validateJson from './validateJson';
 import { awsLog, awsLogDebugLevel } from '~codeyam/utils';
 import { AI, parseJsonSafe } from '~codeyam/ai';
+import convertNullToUndefinedBySchema from './dataStructure/helpers/convertNullToUndefinedBySchema';
 
 const DEFAULT_SCENARIO_NAME = 'Default Scenario';
 
@@ -144,8 +145,9 @@ export async function generateDataForScenario({
 
   if (structure.dataForMocks && !fullScenarioData.data.argumentsData) {
     fullScenarioData.data.argumentsData = [];
-    if (structure.arguments && !fullScenarioData.data.argumentsData) {
-      fullScenarioData.data.argumentsData = [];
+    // Populate argumentsData from structure.arguments using top-level data values
+    // Bug fix: removed redundant !argumentsData check that was always false after setting to []
+    if (structure.arguments) {
       for (let i = 0; i < structure.arguments.length; ++i) {
         if (!fullScenarioData.data.argumentsData[i]) {
           fullScenarioData.data.argumentsData[i] = {};
@@ -166,6 +168,27 @@ export async function generateDataForScenario({
     }
   }
 
+  // Convert null values to undefined based on schema type constraints.
+  // LLM uses null for "no value" (JSON doesn't support undefined), but TypeScript
+  // types like "string | undefined" don't accept null. This converts null→undefined
+  // for fields typed as "T | undefined" (but preserves null for "T | null").
+  if (structure.dataForMocks && fullScenarioData.data.mockData) {
+    convertNullToUndefinedBySchema(
+      fullScenarioData.data.mockData,
+      structure.dataForMocks,
+    );
+  }
+  if (structure.arguments && fullScenarioData.data.argumentsData) {
+    for (let i = 0; i < fullScenarioData.data.argumentsData.length; i++) {
+      if (structure.arguments[i]) {
+        convertNullToUndefinedBySchema(
+          fullScenarioData.data.argumentsData[i],
+          structure.arguments[i],
+        );
+      }
+    }
+  }
+
   return {
     scenarioData: fullScenarioData,
     llmCall: { name: scenario.name, id: llmCall.id },
@@ -284,9 +307,9 @@ export const generateSystemMessage = (
   const scenarioType = defaultScenario
     ? `## Default Scenario
 Generate COMPLETE, robust data for the entire data structure.
-- Fill ALL fields with realistic values (except error attributes)
-- Arrays should have 2-3 items
-- Don't skip nested attributes
+- Fill ALL fields with realistic values (except error attributes and key attributes set to null or undefined)
+- Arrays should have 3-5 items to provide realistic test data variety
+- Don't skip nested attributes unless the key attributes specify a parent attribute should be null or undefined
 - This provides the baseline data for all other scenarios`
     : `## Non-Default Scenario
 Generate ONLY the differences from the default scenario.
@@ -317,16 +340,19 @@ Use for relative dates. Code runs in Node (no browser APIs, no external librarie
 \`\`\`
 Use simple elements only (\`<div>\`, \`<span>\`). No custom components.
 
-## Function Keys
-Preserve function call syntax exactly as written in the structure:
-\`\`\`json
-{
-  "mockData": {
-    "useUser()": { "user": { "name": "John" } },
-    "from().select()": [{ "id": "1" }]
-  }
-}
-\`\`\`
+### Arrays
+- Arrays should have many items (at least 4) unless specified otherwise
+- Each item must follow the exact structure provided
+- In general we want robust data, not minimal data unless specified otherwise
+
+## CRITICAL: Preserve Exact Structure
+Your response MUST mirror the EXACT nested structure provided in mockData Structure.
+- Do NOT reorganize, split, or create duplicate keys
+- The hierarchy of nested objects must match exactly what was provided unless overridden by scenario rules
+- Only change the leaf VALUES (replacing type descriptions like "string" with actual data like "hello")
+- Copy the key strings EXACTLY from the structure
+- Do NOT modify type parameters, arguments, or any part of the key
+- The keys preserve the exact function call as written in the original code
 
 ## Response Format
 \`\`\`json
@@ -344,7 +370,7 @@ Preserve function call syntax exactly as written in the structure:
 ## Rules
 - Valid JSON only—no raw code outside markers
 - No \`undefined\`—use \`null\` or omit
-- No data references (can't use \`posts[0]\` elsewhere—duplicate the value)
+- No data references (can't use \`posts[0]\` elsewhere — duplicate the value)
 - Scenario name must match exactly: "${scenarioName}"
 - Empty mockData: \`{}\`, empty argumentsData: \`[]\`
 `;

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

@@ -8,6 +8,7 @@ import {
   PlaywrightInstruction,
   ReadonlyAnalysisMap,
   Scenario,
+  ValueOptionRef,
 } from '~codeyam/types';
 // import findMatchingAttribute from './findMatchingAttribute';
 import { awsLog } from '~codeyam/utils';
@@ -18,14 +19,20 @@ export interface ScenarioResult {
   name: string;
   testName: string;
   description: string;
-  // New format: { dataStructurePath: { localVariable, instruction } }
-  // Old format (deprecated): { path: instruction_string }
+  /**
+   * Key attribute instructions with structured value references.
+   * Format: { dataStructurePath: { localVariable, instruction, valueOptionRef? } }
+   */
   keyAttributeInstructions: {
     [key: string]:
       | string
       | {
           localVariable: string;
           instruction: string;
+          /** Reference to validValueOption index for tracking coverage */
+          valueOptionRef?: ValueOptionRef;
+          /** Reference to errorValueOption index for error scenarios */
+          errorOptionRef?: ValueOptionRef;
         };
   };
   codeSnippet: string;
@@ -212,6 +219,17 @@ Focus scenarios on demonstrating this specific behavior change.
 
 ${contextSection}${scenarioCountText}
 
+## Coverage Goals (IMPORTANT)
+Your primary goal is to MAXIMIZE coverage of key attributes across all scenarios:
+
+1. **Use ALL validValueOptions**: Each key attribute has indexed \`validValueOptions\`. Across your scenarios, try to use EVERY option at least once. If an attribute has 3 options (indices 0, 1, 2), create scenarios that collectively cover all 3.
+
+2. **Prioritize attributes with dependencies**: Key attributes with a \`dependencies\` array are HIGH PRIORITY - they control conditionally-rendered content. Create scenarios that satisfy these dependencies to reveal gated UI/behavior.
+
+3. **Cover conditional branches**: Use \`codeUsages\` to identify all conditional paths. If code shows \`status === 'active'\` and \`status === 'pending'\`, ensure scenarios cover BOTH values.
+
+4. **Vary values strategically**: Don't repeat the same validValueOption across scenarios unless necessary. Use different indices to maximize coverage.
+
 ## Default Scenario Rules
 The FIRST scenario MUST be named exactly "${DEFAULT_SCENARIO_NAME}" (case-sensitive).
 - Fill ALL key attributes using values from their \`validValueOptions\` list
@@ -219,23 +237,69 @@ The FIRST scenario MUST be named exactly "${DEFAULT_SCENARIO_NAME}" (case-sensit
 - Ignore error-related attributes (set to null)
 - NEVER include \`playwrightInstructions\` - we need a screenshot BEFORE any user interaction
 - Do NOT add playwrightInstructions even if the component has forms/buttons - default shows initial state only
+- **For attributes WITH dependencies**: The Default scenario should satisfy ALL dependencies so the attribute's effect is visible
 
 ## Other Scenarios
 - Each produces DISTINCT output (visual: different screenshot; backend: different return/side-effect)
+- **Use DIFFERENT validValueOptions** than the Default scenario - this is how we achieve coverage
 - Only specify attributes that DIFFER from default
+- Target uncovered validValueOptions: check which indices you haven't used yet
 - May include \`playwrightInstructions\` for user interactions (clicks, form fills)
 
+## Using codeUsages for Branch Coverage
+Key attributes may include a \`codeUsages\` array showing exactly where they're used in conditionals:
+\`\`\`json
+{
+  "codeUsages": [
+    { "line": 45, "code": "if (status === 'active')", "context": "Used in if statement (comparison check)" }
+  ]
+}
+\`\`\`
+Use this to ensure scenarios cover all conditional branches. If you see \`status === 'active'\`, create scenarios for both active AND non-active states.
+
+## Handling Dependencies (Compound Conditionals) - HIGH PRIORITY
+Key attributes with \`dependencies\` are the MOST IMPORTANT to cover because they reveal conditionally-gated content that only appears when multiple conditions are satisfied together.
+
+**Why this matters**: If you see \`items.length > 0 && !isLoading && !hasError\`, the content only renders when ALL THREE conditions are true. Missing even one dependency means the UI won't show.
+
+**Strategy for dependent attributes**:
+1. **Default scenario**: MUST satisfy ALL dependencies of the highest-impact key attributes
+2. **Other scenarios**: Can vary the dependent values to show alternative states (e.g., what happens when isLoading=true)
+
+When a key attribute has dependencies like:
+\`\`\`json
+{
+  "dependencies": [
+    { "path": "signature[0].isLoading", "requiredValue": false },
+    { "path": "signature[0].hasError", "requiredValue": false }
+  ]
+}
+\`\`\`
+The Default scenario MUST set BOTH dependent attributes to their required values so the key attribute's effect is visible.
+
+**Creating scenarios for dependent pathways**:
+- Create at least one scenario where ALL dependencies are satisfied (usually Default)
+- Consider creating additional scenarios that intentionally break dependencies to show the "hidden" state
+
 ## keyAttributeInstructions Format
-Use \`dataStructurePath\` as key, include both variable name and instruction:
+Use \`dataStructurePath\` as key. Include variable name, instruction, AND a valueOptionRef that references which validValueOption you're using:
 \`\`\`json
 {
   "useDiffModal().diffView": {
     "localVariable": "diffView",
-    "instruction": "Set to 'split' mode"
+    "instruction": "Set to 'split' 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).
+
 ## playwrightInstructions (optional, non-default only)
 \`\`\`json
 {
@@ -263,24 +327,63 @@ Use when: data only appears after user action (button click, form submit), or ke
   "dataScenarios": [
     {
       "name": "${DEFAULT_SCENARIO_NAME}",
-      "testName": "it(\"displays notifications with unread indicator\")",
-      "description": "Default state with 3 unread and 2 read notifications",
+      "testName": "it(\"displays items list with data\")",
+      "description": "Shows item list when data is loaded and no errors",
       "keyAttributeInstructions": {
-        "useNotifications().notifications[]": { "localVariable": "notifications[]", "instruction": "Create 5 notifications" },
-        "useNotifications().notifications[].read": { "localVariable": "notifications[].read", "instruction": "false for 3, true for 2" }
+        "useData().items[]": {
+          "localVariable": "items[]",
+          "instruction": "Array with 3 items",
+          "valueOptionRef": { "index": 0, "refType": "exact" }
+        },
+        "useData().isLoading": {
+          "localVariable": "isLoading",
+          "instruction": "false - satisfies dependency for items to show",
+          "valueOptionRef": { "index": 1, "refType": "exact" }
+        },
+        "useData().status": {
+          "localVariable": "status",
+          "instruction": "Set to 'success'",
+          "valueOptionRef": { "index": 0, "refType": "exact" }
+        }
+      }
+    },
+    {
+      "name": "Loading state",
+      "testName": "it(\"shows spinner when loading\")",
+      "description": "Data is loading - items hidden, spinner shown",
+      "keyAttributeInstructions": {
+        "useData().isLoading": {
+          "localVariable": "isLoading",
+          "instruction": "true - breaks dependency, items won't show",
+          "valueOptionRef": { "index": 0, "refType": "exact" }
+        },
+        "useData().status": {
+          "localVariable": "status",
+          "instruction": "Set to 'loading' for coverage of loading state",
+          "valueOptionRef": { "index": 1, "refType": "exact" }
+        }
       }
     },
     {
       "name": "Empty state",
-      "testName": "it(\"shows placeholder when no notifications\")",
-      "description": "User has no notifications",
+      "testName": "it(\"shows empty message when no items\")",
+      "description": "No items to display",
       "keyAttributeInstructions": {
-        "useNotifications().notifications[]": { "localVariable": "notifications[]", "instruction": "Empty array" }
+        "useData().items[]": {
+          "localVariable": "items[]",
+          "instruction": "Empty array [] to show empty state",
+          "valueOptionRef": { "index": 1, "refType": "exact" }
+        }
       }
     }
   ]
 }
 \`\`\`
+Note how the example:
+- Default satisfies ALL dependencies (isLoading=false) so items content shows
+- "Loading state" uses a different valueOptionRef for status to cover that code path
+- "Empty state" covers the empty array case to maximize coverage
+- Instructions describe the VALUE, not the index (e.g., "Empty array []" not "uses index 1")
 `;
 }