@codeyam/codeyam-cli 0.1.0-staging.8aea589 → 0.1.0-staging.da5baf5

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

@@ -41,7 +41,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 +52,112 @@ 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,
+    }));
+
+  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,
+        }));
+        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,36 +19,28 @@ 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,
+    })),
+    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,
@@ -57,7 +49,15 @@ ${JSON.stringify(
   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

@@ -34,6 +34,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 +70,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 +211,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 ?? {};
+}

package/analyzer-template/packages/analyze/src/lib/FileAnalyzer.ts

@@ -278,11 +278,16 @@ export class FileAnalyzer {
 
         for (let i = 0; i < uniqueRelevantExpressions.length; i++) {
           const relevantExpression = uniqueRelevantExpressions[i];
-          if (
-            relevantExpression.exportName === '*' &&
+          // Resolve namespace imports for local packages (not external libraries).
+          // A module is local if it's not external OR if it resolves to a path outside node_modules
+          // (handles local monorepo packages like @codeyam/ui-components).
+          // If resolvedFileName is undefined, we can't determine location, so treat as external.
+          const isLocalModule =
             resolvedModule &&
-            !resolvedModule.isExternalLibraryImport
-          ) {
+            (!resolvedModule.isExternalLibraryImport ||
+              (resolvedModule.resolvedFileName &&
+                !resolvedModule.resolvedFileName.includes('node_modules')));
+          if (relevantExpression.exportName === '*' && isLocalModule) {
             uniqueRelevantExpressions.splice(i, 1);
             uniqueRelevantExpressions.push(
               ...this.resolveNamespaceImport(
@@ -295,11 +300,18 @@ export class FileAnalyzer {
         }
 
         if (uniqueRelevantExpressions.length > 0) {
-          // Debug logging for ./types imports
+          // A module is external if TypeScript says so AND the resolved path is in node_modules.
+          // This handles local monorepo packages (like @codeyam/ui-components) which TypeScript
+          // marks as isExternalLibraryImport=true because they're symlinked, but actually
+          // resolve to files inside the project (not in node_modules).
+          const isExternalLibrary =
+            (resolvedModule?.isExternalLibraryImport ?? true) &&
+            (resolvedModule?.resolvedFileName?.includes('node_modules') ??
+              true);
           return [
             importedFilePath,
             {
-              externalLibrary: resolvedModule?.isExternalLibraryImport ?? true,
+              externalLibrary: isExternalLibrary,
               resolvedPath: resolvedModule?.resolvedFileName,
               exportInfos: uniqueRelevantExpressions,
             },

package/analyzer-template/packages/analyze/src/lib/files/analyze/analyzeEntities/prepareDataStructures.ts

@@ -12,7 +12,7 @@ import {
   getReturnValue,
   getSourceEquivalencies,
   getUsageEquivalencies,
-  getConditionalUsagesFromCode,
+  getConditionalUsages,
   detectWrapperRequirements,
 } from '~codeyam/ai';
 import type { AnalysisOptions } from '../analyzeEntities';
@@ -94,11 +94,6 @@ export default async function prepareEntityDataStructures(
           }
         }
 
-        // Extract conditional usages from the entity code for key attribute detection
-        const conditionalUsages = entity.code
-          ? getConditionalUsagesFromCode(entity.code)
-          : {};
-
         entity.metadata.isolatedDataStructure = {
           signatureSchema: deduplicateFunctionSchemas(
             isolatedDataStructure.signatureSchema,
@@ -110,10 +105,8 @@ export default async function prepareEntityDataStructures(
             isolatedDataStructure.equivalentSignatureVariables,
           dependencySchemas: clonedDependencySchemas,
           environmentVariables: isolatedDataStructure.environmentVariables,
-          conditionalUsages:
-            Object.keys(conditionalUsages).length > 0
-              ? conditionalUsages
-              : undefined,
+          // Use enriched conditional usages with source tracing from analysis
+          conditionalUsages: isolatedDataStructure.conditionalUsages,
         };
 
         // Detect wrapper requirements (Context providers, etc.)
@@ -290,6 +283,9 @@ async function getEntityDataStructureAndFunctionCalls({
   const clonedRawSignature = { ...rawSignature };
   const clonedRawReturnValue = { ...rawReturnValue };
 
+  // Get enriched conditional usages with source tracing
+  const conditionalUsages = getConditionalUsages(dataStructure);
+
   const isolatedDataStructure = {
     signatureSchema: deduplicateFunctionSchemas(clonedRawSignature),
     returnValueSchema: deduplicateFunctionSchemas(clonedRawReturnValue),
@@ -297,6 +293,8 @@ async function getEntityDataStructureAndFunctionCalls({
       getEquivalentSignatureVariables(dataStructure),
     dependencySchemas,
     environmentVariables: dataStructure.environmentVariables,
+    conditionalUsages:
+      Object.keys(conditionalUsages).length > 0 ? conditionalUsages : undefined,
   };
 
   const functionCalls: Record<string, string[]> = {};

package/analyzer-template/packages/analyze/src/lib/files/analyze/analyzeEntities.ts

@@ -18,7 +18,7 @@ import {
   upsertEntities,
 } from '~codeyam/supabase';
 import { getCandidatesReadyForCapture as getAnalysesReadyForCapture } from './dependencyResolver';
-import { awsLog, awsLogDebugLevel } from '~codeyam/utils';
+import { awsLog, awsLogDebugLevel, Semaphore } from '~codeyam/utils';
 
 const MAX_CONCURRENT_ANALYSES = 100; // fairly arbitrary, but more isn't necessarily better
 
@@ -133,6 +133,10 @@ export default async function analyzeEntities({
   const markedReady = new Set<string>(); // Analyses we've attempted to mark ready
   const analyses: Analysis[] = [];
 
+  // Semaphore to serialize CPU-intensive Structure phase while allowing
+  // I/O-bound KeyAttributes LLM calls to run in parallel
+  const structureSemaphore = new Semaphore(1);
+
   const analysesAlreadyCompletedAtStart =
     commit?.metadata?.currentRun?.analysesCompleted ?? 0;
 
@@ -442,6 +446,7 @@ export default async function analyzeEntities({
           analyzeAsDependency: !allRootEntities.some(
             (e) => e.filePath === entity.filePath && e.name === entity.name,
           ),
+          structureSemaphore,
           ...options,
           force,
         }),