@codeyam/codeyam-cli 0.1.0-staging.1 → 0.1.0-staging.596f0eb

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

@@ -1,4 +1,5 @@
 import {
+  DataStructure,
   Entity,
   Scenario,
   ReadonlyAnalysisMap,
@@ -8,6 +9,7 @@ import gatherRelevantDependentKeyAttributes from '../gatherRelevantDependentKeyA
 
 interface GenerateChangesEntityScenariosGeneratorArgs {
   entity: Pick<Entity, 'name' | 'code' | 'metadata'>;
+  mergedDataStructure: Omit<DataStructure, 'equivalentSignatureVariables'>;
   keyAttributes: Analysis['metadata']['keyAttributes'];
   addedKeyAttributes: Analysis['metadata']['keyAttributes'];
   removedKeyAttributes: Analysis['metadata']['keyAttributes'];
@@ -20,6 +22,7 @@ interface GenerateChangesEntityScenariosGeneratorArgs {
 
 export default function generateChangesEntityScenariosGenerator({
   entity,
+  mergedDataStructure,
   keyAttributes,
   addedKeyAttributes,
   removedKeyAttributes,
@@ -30,7 +33,11 @@ export default function generateChangesEntityScenariosGenerator({
   changedDataStructureFields = [],
 }: GenerateChangesEntityScenariosGeneratorArgs) {
   const relevantDependentKeyAttributesFlat =
-    gatherRelevantDependentKeyAttributes(entity, dependentAnalyses);
+    gatherRelevantDependentKeyAttributes(
+      entity,
+      mergedDataStructure,
+      dependentAnalyses,
+    );
 
   // Restructure flat array into nested format: { [filePath]: { [entityName]: KeyAttribute[] } }
   const relevantDependentKeyAttributes: Record<
@@ -41,7 +48,7 @@ export default function generateChangesEntityScenariosGenerator({
     const filePath = (attr as any).filePath;
     const entityName = (attr as any).originalEntityName;
 
-    if (!filePath || !entityName) continue; // Skip if missing required fields
+    if (!filePath || !entityName) continue;
 
     if (!relevantDependentKeyAttributes[filePath]) {
       relevantDependentKeyAttributes[filePath] = {};
@@ -52,128 +59,118 @@ export default function generateChangesEntityScenariosGenerator({
     relevantDependentKeyAttributes[filePath][entityName].push(attr);
   }
 
-  return `Added Key Attributes:
-
-\`\`\`
-${
-  addedKeyAttributes && addedKeyAttributes.length > 0
-    ? JSON.stringify(
-        addedKeyAttributes.map((ka) => ({
-          dataStructurePath: ka.dataStructurePath, // Full path in mockData
-          localVariable: ka.internalPath, // Local variable name
-          description: ka.description,
-          validValueOptions: ka.validValueOptions,
-        })),
-        null,
-        2,
-      )
-    : 'None'
-}
-\`\`\`
-
-Removed Key Attributes:
-
-\`\`\`
-${removedKeyAttributes && removedKeyAttributes.length > 0 ? JSON.stringify(removedKeyAttributes, null, 2) : 'None'}
-\`\`\`
-
-${
-  changedDataStructureFields.length > 0
-    ? `Changed Data Structure Fields:
-
-The following fields in the data structure have changed (type changed, added, or removed):
-
-\`\`\`
+  const formatKeyAttrs = (attrs: Analysis['metadata']['keyAttributes']) =>
+    attrs.map((ka) => ({
+      dataStructurePath: ka.dataStructurePath,
+      localVariable: ka.internalPath,
+      description: ka.description,
+      validValueOptions: ka.validValueOptions,
+      // Include new fields when present
+      ...(ka.valueType && { valueType: ka.valueType }),
+      ...(ka.dependencies && { dependencies: ka.dependencies }),
+    }));
+
+  const addedSection =
+    addedKeyAttributes?.length > 0
+      ? JSON.stringify(formatKeyAttrs(addedKeyAttributes), null, 2)
+      : 'None';
+
+  const removedSection =
+    removedKeyAttributes?.length > 0
+      ? JSON.stringify(removedKeyAttributes, null, 2)
+      : 'None';
+
+  const changedFieldsSection =
+    changedDataStructureFields.length > 0
+      ? `
+## Changed Data Structure Fields
+Fields that changed type, were added, or removed:
+\`\`\`json
 ${JSON.stringify(changedDataStructureFields, null, 2)}
 \`\`\`
 
-**IMPORTANT**: For scenarios that reference these changed fields in their keyAttributeInstructions, you MUST regenerate those specific instructions to match the new data structure. For example:
-- If "stats.visualEntities" changed from an array to a number, update keyAttributeInstructions from "Array of 10 objects" to "10 (count of visual entities)"
-- If a field was removed, remove it from keyAttributeInstructions
-- If a field was added, you may add it to keyAttributeInstructions if relevant for the scenario
-
-Fields that did NOT change can retain their existing keyAttributeInstructions.
-
+**Update keyAttributeInstructions for affected scenarios** (e.g., if "stats.visualEntities" changed from array to number).
 `
-    : ''
-}
-Existing Key Attributes:
-
-\`\`\`
+      : '';
+
+  const existingScenariosJson = JSON.stringify(
+    existingScenarios
+      .filter((s) => (error ? !!s.metadata.error : !s.metadata.error))
+      .map((s) => ({
+        name: s.name,
+        description: s.description,
+        keyAttributeInstructions: s.metadata.keyAttributeInstructions,
+        playwrightInstructions: s.metadata.playwrightInstructions,
+      })),
+    null,
+    2,
+  );
+
+  const diffSection = commitDiff
+    ? `
+## Code Change (Diff)
+\`\`\`diff
+${commitDiff}
+\`\`\``
+    : '';
+
+  const dependencySection =
+    !error &&
+    relevantDependentKeyAttributes &&
+    Object.keys(relevantDependentKeyAttributes).length > 0
+      ? `
+## Dependency Key Attributes
+\`\`\`json
 ${JSON.stringify(
-  keyAttributes.map((ka) => ({
-    dataStructurePath: ka.dataStructurePath, // Full path in mockData
-    localVariable: ka.internalPath, // Local variable name
-    description: ka.description,
-    validValueOptions: ka.validValueOptions,
-  })),
+  Object.keys(relevantDependentKeyAttributes).reduce((acc: any, path) => {
+    acc[path] = Object.keys(relevantDependentKeyAttributes[path]).reduce(
+      (entityAcc: any, entityName) => {
+        entityAcc[entityName] = relevantDependentKeyAttributes[path][
+          entityName
+        ].map((ka: any) => ({
+          dataStructurePath: ka.dataStructurePath,
+          localVariable: ka.path || ka.internalPath,
+          description: ka.description,
+          validValueOptions: ka.validValueOptions,
+          // Include new fields when present
+          ...(ka.valueType && { valueType: ka.valueType }),
+          ...(ka.dependencies && { dependencies: ka.dependencies }),
+        }));
+        return entityAcc;
+      },
+      {},
+    );
+    return acc;
+  }, {}),
   null,
   2,
 )}
-\`\`\`
-
-Existing Scenarios:
+\`\`\``
+      : '';
 
+  return `## Added Key Attributes
+\`\`\`json
+${addedSection}
 \`\`\`
-${JSON.stringify(
-  existingScenarios
-    .filter((s) => (error ? !!s.metadata.error : !s.metadata.error))
-    .map((s) => ({
-      name: s.name,
-      description: s.description,
-      keyAttributeInstructions: s.metadata.keyAttributeInstructions,
-      playwrightInstructions: s.metadata.playwrightInstructions,
-    })),
-  null,
-  2,
-)}
-\`\`\`
-
-${
-  commitDiff
-    ? `
-Code Change:
 
+## Removed Key Attributes
+\`\`\`json
+${removedSection}
 \`\`\`
-${commitDiff}
+${changedFieldsSection}
+## Current Key Attributes
+\`\`\`json
+${JSON.stringify(formatKeyAttrs(keyAttributes), null, 2)}
 \`\`\`
-`
-    : ''
-}
-Function Code:
 
+## Existing Scenarios
+\`\`\`json
+${existingScenariosJson}
 \`\`\`
-${entity.code}
-\`\`\`
+${diffSection}
 
-${
-  !error &&
-  relevantDependentKeyAttributes &&
-  Object.keys(relevantDependentKeyAttributes).length > 0
-    ? `Key Attributes for Dependencies:
-\`\`\`
-${JSON.stringify(
-  Object.keys(relevantDependentKeyAttributes).reduce((acc: any, path) => {
-    acc[path] = Object.keys(
-      (relevantDependentKeyAttributes as any)[path],
-    ).reduce((entityAcc: any, entityName) => {
-      entityAcc[entityName] = (relevantDependentKeyAttributes as any)[path][
-        entityName
-      ].map((ka: any) => ({
-        dataStructurePath: ka.dataStructurePath, // Full path in mockData
-        localVariable: ka.path || ka.internalPath, // Local variable name
-        description: ka.description,
-        validValueOptions: ka.validValueOptions,
-      }));
-      return entityAcc;
-    }, {});
-    return acc;
-  }, {}),
-  null,
-  2,
-)}
-\`\`\``
-    : ''
-}
-`;
+## Current Code
+\`\`\`typescript
+${entity.code}
+\`\`\`${dependencySection}`;
 }

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

@@ -1,35 +1,16 @@
 import { Entity } from '~codeyam/types';
 
 export default function generateEntityDocumentationGenerator(entity: Entity) {
-  return `Here is the code for ${entity.name}:
-  
-"""
-${entity.code}
-"""
-
-What does this code do? Please create documentation for this code. 
-
-- Start with an overview that describes the overall intent of the code. Be concise in your language. Immediately start with the intent of the code. Here is an example Overview:
+  return `## Task
+Document the following code.
 
-\`\`\` Overview
-Displays details about a specific Git commit. It shows the commit message, author, date, and provides a link to the commit on GitHub. Users can copy the commit SHA to their clipboard, with a visual indication of the copy action.
+## Code
+\`\`\`typescript
+${entity.code}
 \`\`\`
 
-Note that it does not mention the name of the function but dives directly into what the code does in concise language followed by a small amount of detail.
-
-- Next, specify the inputs (with details about types, how the input is used, and examples) and expected outputs (with details about types and examples).
-
-- Finally, provide examples of how the code can be used with clear inputs and outputs for each example. Provide diverse examples (there's no need to include repetitive examples). 
-
-Write the documentation as markdown. Be concise. Use bullets when possible. No one wants to read long paragraphs of text. 
-
-Provide no other text than the documentation in proper markdown using the headers below.
-
-## Overview
-
-## Inputs
-
-## Output
+## Overview Example
+Good: "Displays details about a specific Git commit. Shows the commit message, author, date, and provides a link to GitHub. Users can copy the commit SHA to clipboard."
 
-## Examples`;
+Bad: "The CommitDetails function takes a commit object..." (mentions the function name)`;
 }

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

@@ -11,50 +11,45 @@ export default function generateEntityScenarioDataGenerator(
     return incompleteResponse;
   }
 
-  return `## Scenarios
+  const scenarioJson = JSON.stringify(
+    {
+      name: scenario.name,
+      description: scenario.description,
+      keyAttributeInstructions: scenario.metadata.keyAttributeInstructions,
+    },
+    null,
+    2,
+  );
 
-This scenario needs mock data to support it:
-\`\`\`
-${JSON.stringify(
-  {
-    name: scenario.name,
-    description: scenario.description,
-    keyAttributeInstructions: scenario.metadata.keyAttributeInstructions,
-  },
-  null,
-  2,
-)}
-\`\`\`
-${
-  defaultScenarioData
+  const defaultDataSection = defaultScenarioData
     ? `
-## Default Scenario Data
-
-Here is the Default Scenario data. The data generated for this scenario will be merged into this Default Scenario data.
-\`\`\`
+## Default Scenario Data (merge base)
+\`\`\`json
 ${JSON.stringify(defaultScenarioData.data, null, 2)}
 \`\`\`
-
 `
-    : ''
-}
-${
-  structure.dataForMocks
-    ? `The mockData structure (for the default scenario provide robust values for the entire structure, excluding error attributes unless specifically requested):
-\`\`\`
+    : '';
+
+  const mockDataSection = structure.dataForMocks
+    ? `## mockData Structure
+\`\`\`json
 ${JSON.stringify(noErrorAttributes(structure.dataForMocks), null, 2)}
-\`\`\`
-`
-    : 'There is no mockData for this file. Return {} for the mockData.'
-}
-    
-${
-  structure.arguments
-    ? `The argumentsData structure (for the default scenario provide robust values for the entire structure, excluding error attributes unless specifically requested):
-\`\`\`
+\`\`\``
+    : '## mockData Structure\nNone—return `{}` for mockData.';
+
+  const argumentsSection = structure.arguments
+    ? `## argumentsData Structure
+\`\`\`json
 ${JSON.stringify(noErrorAttributes(structure.arguments), null, 2)}
+\`\`\``
+    : '## argumentsData Structure\nNone—return `[]` for argumentsData.';
+
+  return `## Scenario
+\`\`\`json
+${scenarioJson}
 \`\`\`
-`
-    : 'There is no argumentsData for this file. Return [] for the argumentsData.'
-}`;
+${defaultDataSection}
+${mockDataSection}
+
+${argumentsSection}`;
 }

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

@@ -19,45 +19,51 @@ export default function generateEntityScenariosGenerator({
     (ka) => ka.dependentEntityName,
   );
 
-  return `Key Attributes:
-
-\`\`\`
-${JSON.stringify(
-  thisEntityKeyAttributes.map((ka) => ({
-    dataStructurePath: ka.dataStructurePath, // Full path in mockData (e.g., "useDiffModal().diffView")
-    localVariable: ka.internalPath, // Local variable name (e.g., "diffView")
-    description: ka.description,
-    validValueOptions: ka.validValueOptions,
-  })),
-  null,
-  2,
-)}
-\`\`\`
-
-Code:
-\`\`\`
-${entity.code}
-\`\`\`
+  const keyAttrsJson = JSON.stringify(
+    thisEntityKeyAttributes.map((ka) => ({
+      dataStructurePath: ka.dataStructurePath,
+      localVariable: ka.internalPath,
+      description: ka.description,
+      validValueOptions: ka.validValueOptions,
+      // Include new fields when present
+      ...(ka.valueType && { valueType: ka.valueType }),
+      ...(ka.dependencies && { dependencies: ka.dependencies }),
+    })),
+    null,
+    2,
+  );
 
-${
-  !error &&
-  relevantDependentKeyAttributes &&
-  Object.keys(relevantDependentKeyAttributes).length > 0
-    ? `Key Attributes for Dependencies:
-\`\`\`
+  const dependencySection =
+    !error &&
+    relevantDependentKeyAttributes &&
+    relevantDependentKeyAttributes.length > 0
+      ? `
+## Dependency Key Attributes
+\`\`\`json
 ${JSON.stringify(
   relevantDependentKeyAttributes.map((ka) => ({
-    dataStructurePath: ka.dataStructurePath, // Full path in mockData
-    localVariable: ka.internalPath, // Local variable name
+    dataStructurePath: ka.dataStructurePath,
+    localVariable: ka.internalPath,
     forDependency: ka.dependentEntityName,
     description: ka.description,
     validValueOptions: ka.validValueOptions,
+    // Include new fields when present
+    ...(ka.valueType && { valueType: ka.valueType }),
+    ...(ka.dependencies && { dependencies: ka.dependencies }),
   })),
   null,
   2,
 )}
 \`\`\``
-    : ''
-}
-`;
+      : '';
+
+  return `## Key Attributes
+\`\`\`json
+${keyAttrsJson}
+\`\`\`
+
+## Code
+\`\`\`typescript
+${entity.code}
+\`\`\`${dependencySection}`;
 }

package/analyzer-template/packages/ai/src/lib/types/index.ts

@@ -55,6 +55,7 @@ export namespace AI {
    */
   export enum Model {
     // OpenAI
+    OPENAI_GPT5_1 = 'openai/gpt-5.1',
     OPENAI_GPT5 = 'openai/gpt-5',
     OPENAI_GPT5_MINI = 'openai/gpt-5-mini',
     OPENAI_GPT5_NANO = 'openai/gpt-5-nano',
@@ -83,6 +84,7 @@ export namespace AI {
     // Anthropic
     ANTHROPIC_CLAUDE_4_5_HAIKU = 'anthropic/claude-4.5-haiku',
     ANTHROPIC_CLAUDE_4_5_SONNET = 'anthropic/claude-4.5-sonnet',
+    ANTHROPIC_CLAUDE_4_5_OPUS = 'anthropic/claude-4.5-opus',
 
     // Deprecated models (kept for backward compatibility)
     PHIND_CODELLAMA = 'phind/codellama',

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

@@ -22,6 +22,12 @@ export interface SerializableFunctionCallInfo {
   callScope: string;
   schema?: Record<string, string>;
   equivalencies?: Record<string, SerializableScopeVariable[]>;
+  /** All call signatures merged into this entry (e.g., logger.info, logger.debug) */
+  allCallSignatures?: string[];
+  /** Variable names that receive the return value of each call */
+  receivingVariableNames?: string[];
+  /** Maps each call signature to the variable that receives its return value */
+  callSignatureToVariable?: Record<string, string>;
 }
 
 export interface SerializableFunctionResult {
@@ -34,6 +40,28 @@ export interface SerializableFunctionResult {
   environmentVariables: string[];
 }
 
+/**
+ * Enriched conditional usage that includes traced source data path.
+ * The sourceDataPath connects a local variable (used in conditionals) back to
+ * the original data attribute from the attributes map.
+ */
+export interface EnrichedConditionalUsage {
+  /** The local variable path (e.g., "activeTab") */
+  path: string;
+  /** The type of condition this attribute is used in */
+  conditionType: 'truthiness' | 'comparison' | 'switch';
+  /** For comparison conditions, the literal values being compared against */
+  comparedValues?: string[];
+  /** Where this conditional usage occurs */
+  location: 'if' | 'ternary' | 'logical-and' | 'switch';
+  /**
+   * The traced source data path in the format "scopeName.path"
+   * e.g., "useParams().functionCallReturnValue['*']"
+   * This connects the local variable to the original data attribute.
+   */
+  sourceDataPath?: string;
+}
+
 export interface SerializableDataStructure {
   // External function calls array
   externalFunctionCalls: SerializableFunctionCallInfo[];
@@ -48,6 +76,13 @@ export interface SerializableDataStructure {
   equivalentSignatureVariables: Record<string, string>;
 
   environmentVariables: string[];
+
+  /**
+   * Conditional usages with source tracing.
+   * Maps local variable path to array of enriched usages that include
+   * the traced source data path.
+   */
+  conditionalUsages?: Record<string, EnrichedConditionalUsage[]>;
 }
 
 /**
@@ -182,3 +217,13 @@ export function getEquivalentSignatureVariables(
 ): Record<string, string> {
   return dataStructure.equivalentSignatureVariables;
 }
+
+/**
+ * Get enriched conditional usages with source tracing.
+ * Returns the conditional usages map, or empty object if not available.
+ */
+export function getConditionalUsages(
+  dataStructure: SerializableDataStructure,
+): Record<string, EnrichedConditionalUsage[]> {
+  return dataStructure.conditionalUsages ?? {};
+}