@codeyam/codeyam-cli 0.1.0-staging.1 → 0.1.0-staging.28f73cf

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

@@ -84,6 +84,17 @@ export class FileAnalyzer {
     }
   }
 
+  /**
+   * Returns only declared entity nodes (not identifier references).
+   * Use this when you need to find entities that can be replaced/mocked.
+   */
+  getAllDeclaredEntityNodes() {
+    if (!this.sourceFile) return {};
+    return lib.asts.sourceFiles.getAllDeclaredEntityNodes({
+      sourceFile: this.sourceFile,
+    });
+  }
+
   getNodeCode(node: ts.Node, removeComments = false) {
     if (!this.sourceFile) return '';
     if (removeComments) {
@@ -138,6 +149,29 @@ export class FileAnalyzer {
     });
   }
 
+  /**
+   * Get the code for a declared entity (not identifier references).
+   * Use this when you need to find code that can be replaced/mocked.
+   */
+  getDeclaredEntityCode(entityName: string, removeComments = false) {
+    if (!this.sourceFile) return '';
+    const entityNode = lib.asts.sourceFiles.getDeclaredEntityNode({
+      entityName,
+      sourceFile: this.sourceFile,
+    });
+
+    if (removeComments) {
+      const printer = ts.createPrinter({ removeComments: true });
+      return printer.printNode(
+        ts.EmitHint.Unspecified,
+        entityNode,
+        this.sourceFile,
+      );
+    }
+
+    return entityNode.getText(this.sourceFile);
+  }
+
   getAllExports(): Record<string, ExportedFunction> {
     if (!this.sourceFile) return {};
     return lib.asts.sourceFiles.getAllExports(this.sourceFile);
@@ -244,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(
@@ -261,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/asts/nodes/index.ts

@@ -163,7 +163,8 @@ export function isFunction(
     ts.isFunctionDeclaration(node) ||
     ts.isFunctionExpression(node) ||
     ts.isArrowFunction(node) ||
-    ts.isCallExpression(node)
+    ts.isCallExpression(node) ||
+    ts.isClassDeclaration(node)
   );
 }
 

package/analyzer-template/packages/analyze/src/lib/asts/sourceFiles/getAllDeclaredEntityNodes.ts

@@ -0,0 +1,238 @@
+import ts from 'typescript';
+
+interface GetAllDeclaredEntityNodesArgs {
+  sourceFile: ts.SourceFile;
+  possibleIdentifierNode?: ts.Node;
+  entityNode?: ts.Node;
+  entities?: { [key: string]: ts.Node };
+}
+
+/**
+ * Returns all declared entity nodes in a source file.
+ *
+ * Unlike getAllEntityNodes, this function only returns actual declarations
+ * (variables, functions, classes, interfaces, types, enums, exports).
+ * It does NOT include identifier references in initializers or call expressions.
+ *
+ * Use this when you need to find entities that can be replaced/mocked.
+ * Use getAllEntityNodes when you need to track all identifiers (e.g., for dependency analysis).
+ */
+export function getAllDeclaredEntityNodes({
+  sourceFile,
+  possibleIdentifierNode,
+  entityNode,
+  entities = {},
+}: GetAllDeclaredEntityNodesArgs): { [key: string]: ts.Node } {
+  try {
+    if (!possibleIdentifierNode) {
+      possibleIdentifierNode = sourceFile;
+    }
+
+    // Handle direct Identifier (e.g., from declaration.name)
+    if (ts.isIdentifier(possibleIdentifierNode)) {
+      if (!entities[possibleIdentifierNode.text]) {
+        entities[possibleIdentifierNode.text] =
+          entityNode ?? possibleIdentifierNode;
+      }
+      return entities;
+    }
+
+    if (ts.isBindingElement(possibleIdentifierNode)) {
+      const lastChild = possibleIdentifierNode.getChildAt(
+        possibleIdentifierNode.getChildCount(sourceFile) - 1,
+      );
+
+      if (ts.isIdentifier(lastChild)) {
+        entities[lastChild.text] = entityNode;
+      } else if (
+        ts.isObjectBindingPattern(lastChild) ||
+        ts.isArrayBindingPattern(lastChild)
+      ) {
+        entities = {
+          ...entities,
+          ...getAllDeclaredEntityNodes({
+            sourceFile,
+            possibleIdentifierNode: lastChild,
+            entityNode,
+            entities,
+          }),
+        };
+      }
+      return entities;
+    }
+
+    possibleIdentifierNode.forEachChild((child) => {
+      try {
+        const safeEntityNode = entityNode ?? child;
+
+        // For VariableDeclaration, only traverse the name (not the initializer)
+        // This prevents registering identifier references as declarations
+        if (ts.isVariableDeclaration(child)) {
+          entities = {
+            ...getAllDeclaredEntityNodes({
+              sourceFile,
+              possibleIdentifierNode: child.name,
+              entityNode: safeEntityNode,
+              entities,
+            }),
+            ...entities,
+          };
+        } else if (
+          ts.isBindingElement(child) ||
+          ts.isModuleDeclaration(child) ||
+          ts.isNamedExports(child)
+        ) {
+          entities = {
+            ...getAllDeclaredEntityNodes({
+              sourceFile,
+              possibleIdentifierNode: child,
+              entityNode: safeEntityNode,
+              entities,
+            }),
+            ...entities,
+          };
+        }
+
+        if (ts.isVariableDeclarationList(child)) {
+          child.declarations.forEach((declaration) => {
+            entities = {
+              ...getAllDeclaredEntityNodes({
+                sourceFile,
+                possibleIdentifierNode: declaration.name,
+                entityNode: safeEntityNode,
+                entities,
+              }),
+              ...entities,
+            };
+          });
+        }
+
+        if (ts.isVariableStatement(child)) {
+          entities = {
+            ...getAllDeclaredEntityNodes({
+              sourceFile,
+              possibleIdentifierNode: child.declarationList,
+              entityNode: safeEntityNode,
+              entities,
+            }),
+            ...entities,
+          };
+        }
+
+        if (ts.isObjectBindingPattern(child)) {
+          const entityNodes = child.elements.reduce((acc, element) => {
+            return {
+              ...getAllDeclaredEntityNodes({
+                sourceFile,
+                possibleIdentifierNode: element,
+                entityNode: safeEntityNode,
+                entities,
+              }),
+              ...acc,
+            };
+          }, {});
+
+          for (const key in entityNodes) {
+            entities[key] = safeEntityNode;
+          }
+        }
+
+        if (ts.isArrayBindingPattern(child)) {
+          entities = {
+            ...entities,
+            ...child.elements.reduce((acc, element) => {
+              return {
+                ...getAllDeclaredEntityNodes({
+                  sourceFile,
+                  possibleIdentifierNode: element,
+                  entityNode: safeEntityNode,
+                  entities,
+                }),
+                ...acc,
+              };
+            }, {}),
+          };
+        }
+
+        if (
+          ts.isFunctionDeclaration(child) ||
+          ts.isTypeAliasDeclaration(child) ||
+          ts.isInterfaceDeclaration(child) ||
+          ts.isClassDeclaration(child) ||
+          ts.isEnumDeclaration(child)
+        ) {
+          if (!entities[child.name?.text ?? 'default']) {
+            entities[child.name?.text ?? 'default'] = safeEntityNode;
+
+            if (ts.isFunctionDeclaration(child) && child.modifiers) {
+              const isDefaultExport =
+                child.modifiers.some(
+                  (modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword,
+                ) &&
+                child.modifiers.some(
+                  (modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword,
+                );
+
+              if (isDefaultExport) {
+                entities['default'] = safeEntityNode;
+              }
+            }
+          }
+        }
+
+        if (ts.isExportDeclaration(child)) {
+          if (child.exportClause) {
+            entities = {
+              ...getAllDeclaredEntityNodes({
+                sourceFile,
+                possibleIdentifierNode: child.exportClause,
+                entityNode: safeEntityNode,
+                entities,
+              }),
+              ...entities,
+            };
+          }
+        }
+
+        if (ts.isExportAssignment(child)) {
+          // For declared entities, always point to the export statement itself
+          // (not the original declaration) so mock replacement works correctly.
+          // e.g., for `export default prisma;`, we want to replace the export
+          // statement, not the prisma variable declaration.
+          entities['default'] = safeEntityNode;
+        }
+
+        if (ts.isExportSpecifier(child)) {
+          const nameText = child.name.getText(sourceFile);
+          if (child.propertyName) {
+            const propertyNameText = child.propertyName.getText(sourceFile);
+            entities[nameText] = entities[propertyNameText] ?? safeEntityNode;
+            if (propertyNameText !== 'default' && !entities[propertyNameText]) {
+              entities[propertyNameText] = safeEntityNode;
+            }
+          } else {
+            entities[nameText] = entities[nameText] ?? safeEntityNode;
+          }
+        }
+      } catch (e) {
+        console.log(
+          'CodeYam Error: Error Getting All Declared Entity Nodes Child',
+          ts.SyntaxKind[child.kind],
+          child.getText(sourceFile),
+          e,
+        );
+        throw e;
+      }
+    });
+
+    return entities;
+  } catch (e) {
+    console.log(
+      'CodeYam Error: Error Getting All Declared Entity Nodes',
+      ts.SyntaxKind[possibleIdentifierNode.kind],
+      possibleIdentifierNode.getText(sourceFile),
+      e,
+    );
+    throw e;
+  }
+}

package/analyzer-template/packages/analyze/src/lib/asts/sourceFiles/getDeclaredEntityNode.ts

@@ -0,0 +1,25 @@
+import ts from 'typescript';
+import * as lib from '../../index';
+
+/**
+ * Get the AST node for a declared entity by name.
+ * Unlike getEntityNode, this only finds actual declarations (not identifier references).
+ */
+export function getDeclaredEntityNode({
+  entityName,
+  sourceFile,
+}: {
+  entityName: string;
+  sourceFile: ts.SourceFile;
+}) {
+  const entityNodes = lib.asts.sourceFiles.getAllDeclaredEntityNodes({
+    sourceFile,
+  });
+  const entityNode = entityNodes[entityName];
+
+  if (!entityNode) {
+    throw new Error('getDeclaredEntityNode: Entity not found');
+  }
+
+  return entityNode;
+}

package/analyzer-template/packages/analyze/src/lib/asts/sourceFiles/index.ts

@@ -11,7 +11,9 @@ export { getSourceFilesForAllImports } from './getSourceFilesForAllImports';
 export { getImportMappings } from './getImportMappings';
 export { getAllEntities } from './getAllEntities';
 export { getAllEntityNodes } from './getAllEntityNodes';
+export { getAllDeclaredEntityNodes } from './getAllDeclaredEntityNodes';
 export { getEntityNode } from './getEntityNode';
+export { getDeclaredEntityNode } from './getDeclaredEntityNode';
 export { getAllExports } from './getAllExports';
 export { getAllExportedNodes } from './getAllExportedNodes';
 export { getImportsAnalysis } from './getImportsAnalysis';

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,
         }),