@codeyam/codeyam-cli 0.1.0-staging.596f0eb → 0.1.0-staging.62d4615

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

@@ -1,271 +0,0 @@
-import completionCall from './completionCall';
-import { saveLlmCall } from '~codeyam/aws/dynamodb';
-import { Analysis, Entity } from '~codeyam/types';
-import generateEntityKeyAttributesGenerator from './promptGenerators/generateEntityKeyAttributesGenerator';
-import { awsLog } from '~codeyam/utils';
-import { AI, DEFAULT_LARGER_MODEL } from '~codeyam/ai';
-import isFrontend from './isFrontend';
-import { gatherAttributesMap } from './promptGenerators/gatherAttributesMap';
-
-interface GenerateChangesEntityKeyAttributesArgs {
-  entity: Entity;
-  existingKeyAttributes: Analysis['metadata']['keyAttributes'];
-  analysis: Analysis;
-  commitDiff: string;
-  model?: AI.Model;
-}
-
-export default async function generateChangesEntityKeyAttributes({
-  entity,
-  existingKeyAttributes,
-  analysis,
-  commitDiff,
-  model,
-}: GenerateChangesEntityKeyAttributesArgs) {
-  awsLog(`CodeYam: Generating entity key attributes`, {
-    filePath: entity.filePath,
-    entityName: entity.name,
-    analysisId: analysis.id,
-    existingKeyAttributes: existingKeyAttributes?.map((a) => a.externalPath),
-  });
-
-  const isolatedDataStructure = entity.metadata?.isolatedDataStructure;
-  const mergedDataStructure = analysis.metadata.mergedDataStructure;
-  const equivalentSignatureVariables =
-    isolatedDataStructure?.equivalentSignatureVariables ?? {};
-  const { attributesMap, associationMap, dataStructurePathMap } =
-    gatherAttributesMap(
-      isolatedDataStructure ?? mergedDataStructure,
-      mergedDataStructure,
-      equivalentSignatureVariables,
-      true,
-    );
-
-  const prompt = generateEntityKeyAttributesGenerator({
-    code: entity.code,
-    attributesMap,
-    existingKeyAttributes,
-    commitDiff,
-  });
-
-  const response = await completionCall({
-    type: `generateChangesEntityKeyAttributes`,
-    systemMessage: isFrontend(entity.filePath)
-      ? FRONTEND_SYSTEM_MESSAGE
-      : BACKEND_SYSTEM_MESSAGE,
-    prompt,
-    model: model ?? DEFAULT_LARGER_MODEL,
-  });
-
-  const llmCall = await saveLlmCall({
-    object_type: 'analysis',
-    object_id: analysis.id,
-    propsJson: {
-      entity: {
-        name: entity.name,
-        filePath: entity.filePath,
-        code: entity.code,
-      },
-      analysis: {
-        id: analysis.id,
-        metadata: {
-          isolatedDataStructure: entity.metadata.isolatedDataStructure,
-          keyAttributes: analysis.metadata?.keyAttributes ?? [],
-        },
-      },
-      commitDiff,
-      model,
-    },
-    ...response.stats,
-  });
-
-  const { completion: keyAttributesString } = response;
-  if (!keyAttributesString) {
-    console.log(
-      `CodeYam Error: Error Generating changes entity key attributes failed: No response from AI`,
-    );
-    return null;
-  }
-
-  awsLog(
-    `LLMCall ${llmCall ? llmCall.id : 'N/A'}: ${entity.filePath} ${entity.name} changes key attributes :>> `,
-    keyAttributesString,
-  );
-
-  const { addedKeyAttributes, removedKeyAttributes } =
-    JSON.parse(keyAttributesString);
-
-  const keyAttributes: Analysis['metadata']['keyAttributes'] = [
-    ...(existingKeyAttributes ?? []),
-  ];
-
-  for (const addedKeyAttribute of addedKeyAttributes ?? []) {
-    const internalPath = addedKeyAttribute.path;
-    const index = keyAttributes.findIndex(
-      (a) => a.internalPath === internalPath,
-    );
-    const fullKeyAttribute = {
-      internalPath,
-      externalPath: associationMap[internalPath],
-      dataStructurePath: dataStructurePathMap[internalPath] || internalPath,
-      description: addedKeyAttribute.description,
-      validValueOptions: addedKeyAttribute.validValueOptions,
-      errorValueOptions: addedKeyAttribute.errorValueOptions,
-      // Preserve new fields from LLM response
-      valueType: addedKeyAttribute.valueType,
-      dependencies: addedKeyAttribute.dependencies,
-    };
-    if (index !== -1) {
-      keyAttributes.splice(index, 1, fullKeyAttribute);
-    } else {
-      keyAttributes.push(fullKeyAttribute);
-    }
-  }
-
-  for (const removedKeyAttribute of removedKeyAttributes ?? []) {
-    const internalPath =
-      typeof removedKeyAttribute === 'string'
-        ? removedKeyAttribute
-        : removedKeyAttribute.path;
-    const index = keyAttributes.findIndex(
-      (a) => a.internalPath === internalPath,
-    );
-    if (index !== -1) {
-      keyAttributes.splice(index, 1);
-    }
-  }
-
-  const sortedUniqueKeyAttributes = keyAttributes
-    .filter(
-      (keyAttribute, index, self) =>
-        self.findIndex(
-          (ka) => ka.internalPath === keyAttribute.internalPath,
-        ) === index,
-    )
-    .filter((keyAttribute) => attributesMap[keyAttribute.internalPath]);
-
-  return {
-    keyAttributes: sortedUniqueKeyAttributes,
-    llmCall,
-  };
-}
-
-const FRONTEND_SYSTEM_MESSAGE = `You are updating the key attributes for a frontend component that was recently changed.
-
-This is an INCREMENTAL update. Existing key attributes should be preserved unless the code change clearly invalidates them. Removing and re-adding attributes across changes causes unnecessary churn.
-
-## Stability Rules
-
-- REMOVE only if the attribute is clearly no longer used (variable deleted, conditional removed, no longer referenced)
-- KEEP marginal attributes—if unsure, preserve rather than remove
-- ADD new attributes freely when warranted
-
-## 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
-
-Note: A conditional that shows a different UI state (e.g., loading screen, redirect message) IS significant—include it. Only exclude guard clauses that render literally nothing.
-
-## Path Format
-
-Only return attributes from the "Attributes and Value Types" list—these are the only values we can control. Use the exact path 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.
-
-## Response Format
-
-For \`validValueOptions\`, include boundary/extreme values that trigger different behavior—but NOT values that would cause errors.
-
-\`\`\`json
-{
-  "addedKeyAttributes": [
-    {
-      "path": "user",
-      "description": "Controls whether the main form or redirect screen displays",
-      "dependencies": [
-        { "projectId": "must be a valid project ID for 'user' to have effect" }
-      ],
-      "valueType": "object",
-      "validValueOptions": ["truthy user object", "null/undefined"]
-    }
-  ],
-  "removedKeyAttributes": ["oldAttribute.path"]
-}
-\`\`\`
-
-Return empty arrays if no changes needed.
-`;
-
-const BACKEND_SYSTEM_MESSAGE = `You are updating the key attributes for a backend function that was recently changed.
-
-This is an INCREMENTAL update. Existing key attributes should be preserved unless the code change clearly invalidates them. Removing and re-adding attributes across changes causes unnecessary churn.
-
-## Stability Rules
-
-- REMOVE only if the attribute is clearly no longer used (variable deleted, conditional removed, no longer referenced)
-- KEEP marginal attributes—if unsure, preserve rather than remove
-- ADD new attributes freely when warranted
-
-## 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
-
-## Path Format
-
-Only return attributes from the "Attributes and Value Types" list—these are the only values we can control. Use the exact path 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.
-
-## Response Format
-
-For \`validValueOptions\`, include boundary/extreme values that trigger different behavior—but NOT values that would cause errors.
-
-\`\`\`json
-{
-  "addedKeyAttributes": [
-    {
-      "path": "config.enabled",
-      "description": "Controls whether the main processing logic runs",
-      "dependencies": [
-        { "analysisMode": "must be 'full' for 'enabled' to have effect" }
-      ],
-      "valueType": "boolean",
-      "validValueOptions": ["true", "false"]
-    }
-  ],
-  "removedKeyAttributes": ["oldAttribute.path"]
-}
-\`\`\`
-
-Return empty arrays if no changes needed.
-`;

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}
-\`\`\`
-`;
-}