@codeyam/codeyam-cli 0.1.0-staging.e38f7bd → 0.1.0-staging.ea73141

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

@@ -1,294 +0,0 @@
-import completionCall from './completionCall';
-import { saveLlmCall } from '~codeyam/aws/dynamodb';
-import { DataStructure, Entity } 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 isFrontend from './isFrontend';
-import { AI } from '~codeyam/ai';
-import { formatConditionalUsagesForPrompt } from './getConditionalUsagesFromCode';
-import type { 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`, {
-    filePath: entity.filePath,
-    entityName: entity.name,
-  });
-
-  const isolatedDataStructure = entity.metadata?.isolatedDataStructure;
-  const equivalentSignatureVariables =
-    isolatedDataStructure?.equivalentSignatureVariables ?? {};
-  const { attributesMap, associationMap, dataStructurePathMap } =
-    gatherAttributesMap(
-      isolatedDataStructure ?? mergedDataStructure,
-      mergedDataStructure,
-      equivalentSignatureVariables,
-      true,
-    );
-
-  if (Object.keys(attributesMap).length === 0) {
-    console.log(
-      `CodeYam Error: No valid attributes found for ${entity.filePath} ${entity.name}`,
-    );
-    return {
-      keyAttributes: [],
-      llmCall: null,
-    };
-  }
-
-  // Resolve unknown types using heuristics (e.g., "unknown | undefined" -> "string | undefined")
-  const resolvedAttributesMap = fillInDirectSchemaGapsAndUnknowns({
-    scopeName: entity.name,
-    schema: { ...attributesMap },
-  });
-
-  // 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 prompt = generateEntityKeyAttributesGenerator({
-    code: entity.code,
-    attributesMap: resolvedAttributesMap,
-    associationMap,
-    staticAnalysisContext,
-  });
-
-  console.log('Generated prompt for generateEntityKeyAttributes:');
-  console.log(prompt);
-
-  const response = await completionCall({
-    type: `generateEntityKeyAttributes`,
-    systemMessage: isFrontend(entity.filePath)
-      ? FRONTEND_SYSTEM_MESSAGE
-      : BACKEND_SYSTEM_MESSAGE,
-    prompt,
-    model: model ?? DEFAULT_LARGER_MODEL,
-  });
-
-  const llmCall = await saveLlmCall({
-    object_type: 'entity',
-    object_id: entity.sha,
-    propsJson: {
-      entity: {
-        name: entity.name,
-        filePath: entity.filePath,
-        code: entity.code,
-        metadata: {
-          isolatedDataStructure: entity.metadata.isolatedDataStructure,
-        },
-      },
-      model,
-    },
-    ...response.stats,
-  });
-
-  const { completion: keyAttributesString } = response;
-  if (!keyAttributesString) {
-    console.log(
-      `CodeYam Error: Error Generating entity key attributes failed: No response from AI`,
-    );
-    return null;
-  }
-
-  console.log(
-    `LLMCall ${llmCall ? llmCall.id : 'N/A'}: ${entity.filePath} ${entity.name} key attributes :>> `,
-  );
-  console.log(keyAttributesString);
-
-  let keyAttributes = undefined;
-  try {
-    const parsed = JSON.parse(keyAttributesString);
-    keyAttributes = parsed?.keyAttributes;
-  } catch (error) {
-    console.log(
-      `CodeYam Error: Invalid JSON response in generateEntityKeyAttributes for ${entity.filePath} ${entity.name}:`,
-      error,
-    );
-  }
-
-  if (!keyAttributes || !Array.isArray(keyAttributes)) {
-    return { keyAttributes: [], llmCall };
-  }
-
-  // Create reverse lookup: fullPath → internalPath
-  // associationMap is keyed by internalPath with value fullPath (when reverse=true)
-  const fullPathToInternalPath = Object.fromEntries(
-    Object.entries(associationMap).map(([internalPath, fullPath]) => [
-      fullPath,
-      internalPath,
-    ]),
-  );
-
-  const fullKeyAttributes = keyAttributes
-    .filter(Boolean)
-    .filter(
-      (keyAttribute, index, self) =>
-        keyAttribute?.fullPath &&
-        self.findIndex((ka) => ka?.fullPath === keyAttribute.fullPath) ===
-          index,
-    )
-    .filter((keyAttribute) => fullPathToInternalPath[keyAttribute.fullPath])
-    .map((keyAttribute) => {
-      const internalPath = fullPathToInternalPath[keyAttribute.fullPath];
-      return {
-        internalPath,
-        externalPath: associationMap[internalPath],
-        dataStructurePath:
-          dataStructurePathMap[internalPath] || keyAttribute.fullPath,
-        description: keyAttribute.description,
-        validValueOptions: keyAttribute.validValueOptions,
-        errorValueOptions: keyAttribute.errorValueOptions,
-        // Preserve new fields from LLM response
-        valueType: keyAttribute.valueType,
-        dependencies: keyAttribute.dependencies,
-      };
-    });
-
-  return {
-    keyAttributes: fullKeyAttributes,
-    llmCall,
-  };
-}
-
-const FRONTEND_SYSTEM_MESSAGE = `You analyze frontend components to identify key data attributes that significantly impact rendering.
-
-## What Makes a Key Attribute
-
-A key attribute is a data path from "Attributes and Value Types" that dramatically changes how the component renders:
-
-- Controls a conditional that shows/hides significant UI sections
-- Changes the component's primary visual state (not just minor text differences)
-- Determines which branch of rendering logic executes
-
-NOT key attributes:
-- Values that only affect non-visible behavior (hrefs, image srcs)
-- Fallback values that won't be used if primary values exist
-- Values that would cause errors if changed
-- Guard clauses that render literally nothing
-
-## Conditional 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.
-
-## 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
-
-If this key attribute is only used if one or more other attributes have specific values, include those dependencies in a \`dependencies\` array.
-
-## 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
-- 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
-
-## Response Format
-
-List all key attributes in order from most impactful to least impactful regarding how dramatically they will change the rendering of the component using the following format:
-
-\`\`\`json
-{
-  "keyAttributes": [
-    {
-      "fullPath": "signature[0].user",
-      "description": "Controls whether the main form or redirect screen displays",
-      "dependencies": [
-        "signature[0].projectId": "must be a valid project ID for 'user' to have effect"
-      ],
-      "valueType": "object",
-      "validValueOptions": ["an empty object {}", "null/undefined"]
-    }
-  ]
-}
-\`\`\`
-`;
-
-const BACKEND_SYSTEM_MESSAGE = `You analyze backend functions to identify key data attributes that significantly impact behavior.
-
-## What Makes a Key Attribute
-
-A key attribute is a data path from "Attributes and Value Types" that dramatically changes the function's behavior:
-
-- Controls a conditional that significantly alters execution flow or return value
-- Determines which branch of logic executes
-- For side-effect functions: changes how external systems are called (database, email, etc.)
-
-NOT key attributes:
-- Fallback values that won't be used if primary values exist
-- Values that would cause errors if changed
-- Guard clauses that return nothing/minimal data
-
-## Conditional 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.
-
-## 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
-
-If this key attribute is only used if one or more other attributes have specific values, include those dependencies in a \`dependencies\` array.
-
-## 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
-- 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
-
-## Response Format
-
-List all key attributes in order from most impactful to least impactful using the following format:
-
-\`\`\`json
-{
-  "keyAttributes": [
-    {
-      "fullPath": "signature[0].config.enabled",
-      "description": "Controls whether the main processing logic runs",
-      "dependencies": [
-        "signature[0].analysisMode": "must be 'full' for 'enabled' to have effect"
-      ],
-      "valueType": "boolean",
-      "validValueOptions": ["true", "false"]
-    }
-  ]
-}
-\`\`\`
-`;

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

@@ -1,67 +0,0 @@
-import { Analysis } from '~codeyam/types';
-
-interface GenerateEntityKeyAttributesGeneratorArgs {
-  code: string;
-  attributesMap: Record<string, string>;
-  associationMap?: Record<string, string>;
-  existingKeyAttributes?: Analysis['metadata']['keyAttributes'];
-  commitDiff?: string;
-  /** Pre-formatted static analysis context showing attributes used in conditionals */
-  staticAnalysisContext?: string;
-}
-
-export default function generateEntityKeyAttributesGenerator({
-  code,
-  attributesMap,
-  associationMap = {},
-  existingKeyAttributes,
-  commitDiff,
-  staticAnalysisContext,
-}: GenerateEntityKeyAttributesGeneratorArgs) {
-  // Build the new format: "fullPath": { variableName: "name", type: "type" }
-  const formattedAttributes = Object.entries(attributesMap)
-    .sort((a, b) => a[0].localeCompare(b[0]))
-    .map(([variableName, type]) => {
-      const fullPath = associationMap[variableName] || variableName;
-      return `"${variableName}":\n  {\n    fullPath: "${fullPath}",\n    type: "${type}"\n  }`;
-    })
-    .join('\n');
-
-  return `Attributes and Value Types:
-
-\`\`\`
-${formattedAttributes}
-\`\`\`
-${staticAnalysisContext ? `\n\nConditional Key Attributes:\n\`\`\`${staticAnalysisContext}\`\`\`\n\n` : ''}
-${
-  existingKeyAttributes
-    ? `
-Existing Key Attributes:
-\`\`\`
-${JSON.stringify(
-  existingKeyAttributes.filter((attr) => attributesMap[attr.internalPath]),
-  null,
-  2,
-)}
-\`\`\`
-
-`
-    : ``
-}
-${
-  commitDiff
-    ? `
-Code Change:
-\`\`\`
-${commitDiff}
-\`\`\`
-
-`
-    : ''
-}
-Code:
-\`\`\`
-${code}
-\`\`\`
-`;
-}

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

@@ -1,156 +0,0 @@
-/**
- * Transforms mock data values to match expected schema types.
- *
- * LLMs sometimes generate values in the wrong format. For example, when analyzing
- * code like `const segments = splat.split('/').filter(Boolean)`, the LLM might
- * output an array like `["scenarios", "abc123"]` even though `splat` is typed as
- * a string and should be `"scenarios/abc123"`.
- *
- * This function walks the mock data and schema in parallel, transforming values
- * that don't match their expected types.
- */
-
-type SchemaValue = string | Record<string, unknown> | unknown[];
-
-/**
- * Gets the base type from a schema type string like "string | undefined" -> "string"
- */
-function getBaseType(schemaType: string): string {
-  // Remove "| undefined", "| null", etc. and get the primary type
-  const parts = schemaType.split('|').map((s) => s.trim());
-  const primaryType = parts.find(
-    (p) => p !== 'undefined' && p !== 'null' && p !== 'never',
-  );
-  return primaryType || parts[0];
-}
-
-/**
- * Transforms a single value to match the expected schema type
- */
-function transformValue(value: unknown, schemaType: string): unknown {
-  if (value === null || value === undefined) {
-    return value;
-  }
-
-  const baseType = getBaseType(schemaType);
-
-  // Array -> String: join with '/' (common for route params like `params['*']`)
-  if (Array.isArray(value) && baseType === 'string') {
-    return value.join('/');
-  }
-
-  // String -> Number
-  if (typeof value === 'string' && baseType === 'number') {
-    const num = Number(value);
-    if (!isNaN(num)) {
-      return num;
-    }
-  }
-
-  // Number -> String
-  if (typeof value === 'number' && baseType === 'string') {
-    return String(value);
-  }
-
-  // Boolean -> String
-  if (typeof value === 'boolean' && baseType === 'string') {
-    return String(value);
-  }
-
-  // String -> Boolean
-  if (typeof value === 'string' && baseType === 'boolean') {
-    return value === 'true';
-  }
-
-  return value;
-}
-
-/**
- * Recursively transforms mock data to match the schema types
- */
-function transformObject(
-  mockData: Record<string, unknown>,
-  schema: Record<string, SchemaValue>,
-  path: string = '',
-): Record<string, unknown> {
-  const result: Record<string, unknown> = {};
-
-  for (const key of Object.keys(mockData)) {
-    const value = mockData[key];
-    const schemaValue = schema[key];
-    const currentPath = path ? `${path}.${key}` : key;
-
-    if (schemaValue === undefined) {
-      // No schema for this key, keep as-is
-      result[key] = value;
-      continue;
-    }
-
-    if (typeof schemaValue === 'string') {
-      // Schema is a type string like "string" or "string | undefined"
-      result[key] = transformValue(value, schemaValue);
-    } else if (
-      typeof schemaValue === 'object' &&
-      schemaValue !== null &&
-      !Array.isArray(schemaValue)
-    ) {
-      // Schema is a nested object
-      if (
-        typeof value === 'object' &&
-        value !== null &&
-        !Array.isArray(value)
-      ) {
-        result[key] = transformObject(
-          value as Record<string, unknown>,
-          schemaValue as Record<string, SchemaValue>,
-          currentPath,
-        );
-      } else {
-        result[key] = value;
-      }
-    } else if (Array.isArray(schemaValue)) {
-      // Schema is an array - transform each item if value is also an array
-      if (Array.isArray(value) && schemaValue.length > 0) {
-        const itemSchema = schemaValue[0];
-        if (typeof itemSchema === 'object' && itemSchema !== null) {
-          result[key] = value.map((item, i) => {
-            if (typeof item === 'object' && item !== null) {
-              return transformObject(
-                item as Record<string, unknown>,
-                itemSchema as Record<string, SchemaValue>,
-                `${currentPath}[${i}]`,
-              );
-            }
-            return item;
-          });
-        } else {
-          result[key] = value;
-        }
-      } else {
-        result[key] = value;
-      }
-    } else {
-      result[key] = value;
-    }
-  }
-
-  return result;
-}
-
-/**
- * Transforms scenario mock data to match expected schema types.
- *
- * @param mockData - The generated mock data from the LLM
- * @param dataForMocks - The schema defining expected types
- * @returns The transformed mock data with values matching expected types
- */
-export default function transformMockDataToMatchSchema(
-  mockData: Record<string, unknown> | undefined,
-  dataForMocks: Record<string, unknown> | undefined,
-): Record<string, unknown> | undefined {
-  if (!mockData || !dataForMocks) {
-    return mockData;
-  }
-
-  return transformObject(mockData, dataForMocks as Record<string, SchemaValue>);
-}

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

@@ -1,115 +0,0 @@
-import {
-  Analysis,
-  Entity,
-  DEFAULT_SCENARIO_NAME,
-  ReadonlyAnalysisMap,
-} from '~codeyam/types';
-import measureAndReportExecutionTime from '../../utils/measureAndReportExecutionTime';
-import { AI, generateEntityKeyAttributes } from '~codeyam/ai';
-import { awsLog } from '~codeyam/utils';
-import { gatherRelevantDependentKeyAttributes } from '~codeyam/ai';
-import { gatherDataForMocks } from './generateScenarioData';
-
-export interface GenerateEntityKeyAttributesArgs {
-  entity: Entity;
-  analysis: Analysis;
-  dependentAnalyses: ReadonlyAnalysisMap;
-  error?: boolean;
-  model: AI.Model;
-  updateProgress?: (detail: string) => void;
-}
-
-export default async function generateKeyAttributes({
-  entity,
-  analysis,
-  dependentAnalyses,
-  error,
-  model,
-  updateProgress,
-}: GenerateEntityKeyAttributesArgs): Promise<void> {
-  if (!['visual', 'library'].includes(entity.entityType)) return;
-
-  // Merge direct dataForMocks with recursively gathered data from dependencies
-  const structure = {
-    arguments: analysis.metadata.scenariosDataStructure?.arguments ?? [],
-    dataForMocks: {
-      ...(analysis.metadata.scenariosDataStructure?.dataForMocks ?? {}),
-      ...gatherDataForMocks(analysis, dependentAnalyses),
-    },
-  };
-
-  awsLog(`🔮 Generating ${error ? 'error ' : ''}scenarios for`, {
-    filePath: entity.filePath,
-    entityName: entity.name,
-    structure,
-  });
-
-  if (
-    !structure ||
-    (Object.keys(structure.dataForMocks ?? {}).length === 0 &&
-      (structure.arguments ?? []).length === 0)
-  ) {
-    if (!error) {
-      analysis.scenarios = [
-        {
-          projectId: analysis.projectId,
-          analysisId: analysis.id,
-          name: DEFAULT_SCENARIO_NAME,
-          description: 'The only external state the component can be in.',
-          metadata: {
-            testName: 'it("renders correctly")',
-            keyAttributeInstructions: {},
-          },
-        },
-      ];
-    }
-
-    return;
-  }
-
-  if (!analysis.metadata.keyAttributes) {
-    const {
-      result: { keyAttributes, llmCall: keyAttributesLLMCall },
-    } = await measureAndReportExecutionTime(
-      () =>
-        generateEntityKeyAttributes({
-          entity,
-          mergedDataStructure: analysis.metadata.mergedDataStructure,
-          model,
-        }),
-      `Generating entity key attributes`,
-      updateProgress,
-    );
-
-    const relevantDependentKeyAttributes = gatherRelevantDependentKeyAttributes(
-      entity,
-      analysis.metadata.mergedDataStructure,
-      dependentAnalyses,
-    );
-
-    analysis.metadata.keyAttributes = [
-      ...keyAttributes,
-      ...relevantDependentKeyAttributes.map((ka) => ({
-        ...ka,
-        // Spread to convert readonly arrays to mutable arrays (with fallback for undefined)
-        validValueOptions: [...(ka.validValueOptions ?? [])],
-        errorValueOptions: [...(ka.errorValueOptions ?? [])],
-        // Convert readonly dependencies array to mutable if present
-        ...(ka.dependencies && {
-          dependencies: ka.dependencies.map((dep) => ({ ...dep })),
-        }),
-      })),
-    ].filter(
-      (ka, index, self) =>
-        self.findIndex((k) => k.internalPath === ka.internalPath) === index,
-    );
-
-    if (keyAttributesLLMCall) {
-      analysis.metadata.llmCalls ||= [];
-      analysis.metadata.llmCalls.push({
-        name: `generateEntityKeyAttributes`,
-        id: keyAttributesLLMCall.id,
-      });
-    }
-  }
-}