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

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

@@ -138,154 +138,98 @@ export default async function generateChangesEntityKeyAttributes({
   };
 }
 
-const FRONTEND_SYSTEM_MESSAGE = `We have a frontend function that was recently changed.
+const FRONTEND_SYSTEM_MESSAGE = `You are updating the key attributes for a frontend component that was recently changed.
 
-Can you help us identify if any of the key data attributes in the function are no longer valid or if any new key data attributes should be added to the list?
+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.
 
-We've provided a list of the existing key data attributes, the commit diff, a list of all data attributes that are now valid, and the function code.
+## Stability Rules
 
-Each key attribute represents a path from a top level variable and that path must be noted exactly as it is in the "Attributes and Value Types" list.
+- 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
 
-Key attributes must come either from the function signature or from a function call that is made from within the function that return data that is used in the function. Please capture the attrribute path exactly from the list.
+## What Makes a Key Attribute
 
-If an attribute has the keyword "functionCallReturnValue" in it, it is a function call that returns data that is used in the function. That keyword simply designated the return value of the function call. If an attribute path has "[]" in it (e.g. "items[]") that represents one item in that array.
+A key attribute is a data path from "Attributes and Value Types" that dramatically changes how the component renders:
 
-## Key Attribute Rules
+- 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
 
-- All key attributes must come from the "Attributes and Value Types" provided. All data traces through these attributes and these are the only attributes we can use to provide data to the function. Only use these attributes. Do not reference internally computed variables. Trace their origin back to an attribute from the "Attributes and Value Types" list.
+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
 
-### Should be a key attribute
+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.
 
-- Changing the value, length (e.g. for strings or arrays), etc of this variable will dramatically change how the component displays (the return value of the function).
+## Path Format
 
-- Is used in a conditional that dramatically alters how the component displays (note: if the conditional compares two or more variables, note which variables are involved and how they must be set to cause different behavior).
+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[]\`).
 
-### Should NOT be a key attribute
+## Response Format
 
-- Changing the value of this variable will cause an error or exception to be thrown.
-
-- Changing the value of this variable will cause a guard clause to be triggered that results in nothing being displayed.
-
-- Changing the value of this variable will cause a minor change in display that is not significant (e.g. slightly different text).
-
-- The value is used as a fallback or alternative for another value and won't even be used if the other value is present.
-
-- The value changes non-visible behavior (e.g. the href in a link or src in an image - all images sources are mocked out).
-
-## Instructions
-
-- Read each line of code. Pay particular attention to the return value of the function and how this frontend component will be displayed. What will cause it display distinctly different but functional and robust results to the user?
-- Find the most impactful key attributes that will change how the frontend component is displayed. This should be a limited subset of the "Attributes and Value Types" provided.
-- Reference the list of existing key attributes to determine if any of them are no longer valid or if any new key attributes should be added.
-- Return each key attribute with the following information:
-  - \`path\`: The path to the data attribute in the code
-  - \`description\`: A short description of the data attribute and how it is used in the code.
-  - \`validValueOptions\`: A list of possible values for the data attribute that should be tested. This should include extreme values that could cause different behavior in the code but these values should not cause an error.
-- Each attribute should reference exactly the path of a data attribute provided in the "Attributes and Value Types" section.
-
-## Response
-
-Please respond by specifying which attributes need to be added or removed. For removed attributes just specify the path that is no longer valid.
+For \`validValueOptions\`, include boundary/extreme values that trigger different behavior—but NOT values that would cause errors.
 
 \`\`\`json
 {
   "addedKeyAttributes": [
     {
-      "path": "notification.read",
-      'percentage": 50,
-      "description": "The read status of the notification determines how the message is displayed.",
-      "validValueOptions": [
-        "true",
-        "false"
-      ],
-      "errorValueOptions": []
-    },
+      "path": "user",
+      "description": "Controls whether the main form or redirect screen displays",
+      "validValueOptions": ["truthy user object", "null/undefined"]
+    }
   ],
-  "removedKeyAttributes": [
-    "notification.message"
-  ]
+  "removedKeyAttributes": ["oldAttribute.path"]
 }
 \`\`\`
 
-## Important
-
-- A key attribute must be an exact attribute path from the "Attributes and Value Types" provided. Do not return any other attribute paths.  The only data we can provide to the function comes from these attributes so any other attribute is useless. For internally computed variables trace them back to one of the higher level variables that we can actually impact. Be sure to match the text from the attribute list exactly including spaces, commas, etc.
+Return empty arrays if no changes needed.
 `;
 
-const BACKEND_SYSTEM_MESSAGE = `We have a function that was recently changed.
-
-Can you help us identify if any of the key data attributes in the function are no longer valid or if any new key data attributes should be added to the list?
-
-We've provided a list of the existing key data attributes, the commit diff, a list of all data attributes that are now valid, and the function code.
+const BACKEND_SYSTEM_MESSAGE = `You are updating the key attributes for a backend function that was recently changed.
 
-Can you help us identify the key data attributes in the code that will cause the function to return distinctly different but functional and robust results?
+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.
 
-We're not interested in causing errors or in high-level guard clauses that result in nothing being returned. We're interested in always returning a robust result that demonstrates the core intent of the function.
+## Stability Rules
 
-In order to do so we want to identify the key data attributes in the code.
+- 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
 
-Each key attribute represents a path from a top level variable and that path must be noted exactly as it is in the "Attributes and Value Types" list.
+## What Makes a Key Attribute
 
-Key attributes must come either from the function signature or from a function call that is made from within the function that return data that is used in the function. Please capture the attrribute path exactly from the list.
+A key attribute is a data path from "Attributes and Value Types" that dramatically changes the function's behavior:
 
-If an attribute has the keyword "functionCallReturnValue" in it, it is a function call that returns data that is used in the function. That keyword simply designated the return value of the function call. If an attribute path has "[]" in it (e.g. "items[]") that represents one item in that array.
+- 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.)
 
-## Key Attribute Rules
+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
 
-- All key attributes must come from the "Attributes and Value Types" provided. All data traces through these attributes and these are the only attributes we can use to provide data to the function. Only use these attributes. Do not reference internally computed variables. Trace their origin back to an attribute from the "Attributes and Value Types" list.
+## Path Format
 
-### Should be a key attribute
+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[]\`).
 
-- Changing the value, length (e.g. for strings or arrays), etc of this variable will dramatically impact the return value of the function.
+## Response Format
 
-- Is used in a conditional that dramatically the execution flow of the function and as a result the return value of the function (note: if the conditional compares two or more variables, note which variables are involved and how they must be set to cause different behavior).
-
-- Note: some functions do not return anything but instead call out to other systems (e.g. send an email, write to a database, etc). In those cases, the key attributes should be those that dramatically change how the function interacts with those other systems.
-
-### Should NOT be a key attribute
-
-- Changing the value of this variable will cause an error or exception to be thrown.
-
-- Changing the value of this variable will cause a guard clause to be triggered that results in nothing or very little being returned.
-
-- The value is used as a fallback or alternative for another value and won't even be used if the other value is present.
-
-## Instructions
-
-- Read each line of code. Pay particular attention to the return value of the function. What data attributes will cause it to return distinctly different but functional and robust results?
-- Find the most impactful key attributes that will impact the return value of the function. This should be a limited subset of the "Attributes and Value Types" provided.
-- Reference the list of existing key attributes to determine if any of them are no longer valid or if any new key attributes should be added.
-- Return each key attribute with the following information:
-  - \`path\`: The path to the data attribute in the code
-  - \`description\`: A short description of the data attribute and how it is used in the code.
-  - \`validValueOptions\`: A list of possible values for the data attribute that should be tested. This should include extreme values that could cause different behavior in the code but these values should not cause an error.
-- Each attribute should reference exactly the path of a data attribute provided in the "Attributes and Value Types" section.
-
-## Response
-
-Please respond by specifying which attributes need to be added or removed. For removed attributes just specify the path that is no longer valid.
+For \`validValueOptions\`, include boundary/extreme values that trigger different behavior—but NOT values that would cause errors.
 
 \`\`\`json
 {
   "addedKeyAttributes": [
     {
-      "path": "notification.read",
-      'percentage": 50,
-      "description": "The read status of the notification determines how the message is displayed.",
-      "validValueOptions": [
-        "true",
-        "false"
-      ],
-      "errorValueOptions": []
-    },
+      "path": "config.enabled",
+      "description": "Controls whether the main processing logic runs",
+      "validValueOptions": ["true", "false"]
+    }
   ],
-  "removedKeyAttributes": [
-    "notification.message"
-  ]
+  "removedKeyAttributes": ["oldAttribute.path"]
 }
 \`\`\`
 
-## Important
-
-- A key attribute must be an exact attribute path from the "Attributes and Value Types" provided. Do not return any other attribute paths.  The only data we can provide to the function comes from these attributes so any other attribute is useless. For internally computed variables trace them back to one of the higher level variables that we can actually impact. Be sure to match the text from the attribute list exactly including spaces, commas, etc.
+Return empty arrays if no changes needed.
 `;

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

@@ -322,187 +322,83 @@ export default async function generateChangesEntityScenarioData({
 const generateChangesSystemMessage = (
   scenarioName: string,
   isDefault: boolean,
-) => `## Overview
-- You will be provided with a structure for scenario data, the "mockData structure", and for the arguments of the function, the "argumentsData structure", and a scenario describing a new state of data for this function.
-
-- Your goal is to modify the existing data, if necssary, to satisfy the current scenario "keyAttributeInstructions" and the data structures.
-
-## Provided Information
-
-- The "mockData structure" and "argumentsData structure" describe all of the data required for the simulation to work. ${isDefault ? 'Generate valid data for every object, attribute, and nested attribute described in the data structure' : 'Ensure between the default data and the data for this scenario all attributes are appropriately filled in unless they are intentionally not defined'}. 
-
-- The "Scenario" provides instruction on how to generate the data for this scenario. 
-
-${
-  isDefault
-    ? ''
-    : `- The "Default Scenario" provides the default scenario data. The data for this scenario will be merged into the ${DEFAULT_SCENARIO_NAME} data to produce the full data.
-`
-}
-- The "Existing Scenario" provides the data for this scenario prior to the code change. This data should be maintained as much as possible. It should only be edited to satisfy the requirements for this scenario.
-
-## Instructions
-${
-  isDefault
-    ? `
-- As the ${DEFAULT_SCENARIO_NAME} please ensure all data is filled in to meet the needs of the current code.
-
-- The one exception to this is error data. Sometimes the data structure will contain structures for both success and error data. In this case you should only fill in the success data and leave out the error data completely.
-
-- Always use realistic data, filling in all arrays, attributes, and sub-attributes (except for error data), creating a high quality default scenario.
-`
-    : `
-- If the code change and new "keyAttributeInstructions" dictate changes to the "Existing Scenario" then make those changes, returning the complete data that will be merged into the "Default Scenario" data. There is no need to duplicate any of the "Default Scenario" data.
-
-- If you need to remove data from the ${DEFAULT_SCENARIO_NAME} data then you can set any attribute to null, which will remove it during the merge process.`
-}
-- If the type is described as "any" then create a realistic example of that type based on its name. If the type is "date" or "timestamp" then use the instructione below to generate a dynamic date or timestamp. If the type is "*a void function*" then provide a void function per the instructions below. If the key value is "*a function that returns*" then provide a function that returns a value as described by the "*a function that returns*".
-
-- If the data in the "Existing Scenario" is sufficient then return the following:
+) => {
+  const scenarioType = isDefault
+    ? `## Default Scenario (Incremental Update)
+Preserve existing data and only modify what's necessary for the new structure.
+- If structure unchanged and data sufficient, return empty data: \`{ "data": {} }\`
+- If new fields added, fill them with realistic values
+- Fill ALL fields with realistic values (except error attributes)
+- NEVER include "error" fields—omit entirely`
+    : `## Non-Default Scenario (Incremental Update)
+Preserve existing data and only modify what changed.
+- If no changes needed, return empty data: \`{ "data": {} }\`
+- Include only fields that need to change from existing + default
+- Set to \`null\` to remove data during merge
+- NEVER include "error" fields—omit entirely`;
+
+  return `You are updating scenario data after a code change. Preserve existing data where possible.
+
+${scenarioType}
+
+## CRITICAL: NO ERROR DATA
+NEVER include "error" fields in responses. Skip them entirely.
+- If structure has \`{ data: {...}, error: {...} }\`, only fill \`data\`
+- Leave out any attribute named "error"—do not set to null, omit entirely
+
+## Special Markers
+
+### Dynamic Dates (\`~~codeyam-code~~\`)
+\`\`\`json
+{ "createdAt": { "~~codeyam-code~~": "new Date(Date.now() - 24*60*60*1000)" } }
+\`\`\`
+Use for relative dates. Code runs in Node (no browser APIs, no external libraries).
 
+### JSX Children (\`~~codeyam-jsx~~\`)
+\`\`\`json
+{ "children": { "~~codeyam-jsx~~": "<div>Hello</div>" } }
 \`\`\`
-{
-  "scenarioData": {
-    "scenarioName: "${scenarioName}",
-    "data": {}
-  }
-}
+Use simple elements only (\`<div>\`, \`<span>\`). No custom components.
+
+### Functions (\`~~codeyam-code~~\`)
+\`\`\`json
+{ "onClick": { "~~codeyam-code~~": "() => console.log('clicked')" } }
 \`\`\`
 
-## Example Response
+## Function Keys
+Preserve function call syntax exactly as written in the structure.
 
+## Response Format
+\`\`\`json
 {
   "scenarioData": {
     "scenarioName": "${scenarioName}",
-    "data': {
-      "mockData": {
-        "user": {
-          "name": "John Doe",
-          "metadata": {
-            "hobbies": ["fishing", "hiking", "camping"]
-            "favoriteColor": "blue",
-          },
-          "joinedAt": {
-            "~~codeyam-code~~": "new Date(Date.now() - 3 * 24 * 60 * 60 * 1000)"         
-          },
-          "loadRank: {
-            "~~codeyam-code~~": "() => { console.log('loadRank called'); return { rank: 5 } }" 
-          }
-        },
-        "project": {
-          "name": "New Project",
-          "slug": "new-project",
-          "files": [
-            {
-              "name": "File 1",
-              "slug": "file-1",
-              "content": "This is the content of file 1"
-            },
-            {
-              "name": "File 2",
-              "slug": "file-2",
-              "content": "This is the content of file 2"
-            },
-            {
-              "name": "File 3",
-              "slug": "file-3",
-              "content": "This is the content of file 3"
-            }
-          ]
-        }
-      },
-      "argumentsData": [
-        {
-          "open": "true",
-          "onClick": {
-            "~~codeyam-code~~": "() => console.log('clicked')"
-          },
-          "children: "Click Me!"        
-        }      
-      ]        
-    }
-  }
-}
-
-## scenarioData
-
-You will return a JSON object called scenarioData containing the name and data for this scenario.
-
-If you encounter a "date" then you should use "~~codeyam-code~~" along with code in string format. That string will be evaled to create the date or timestamp needed.
-
-For example the "timestamp" above should probably not be a hard-coded timestamp but should be a function that returns a timestamp. If you want to return a timestamp that is 24 hours in the future, you would return this object:
-
-\`\`\`
-{
-  "scenarioData": {
-    "scenarioName": ${scenarioName},
     "data": {
-      "mockData": {
-        "dataLoaders": {
-          "fetchUser()": {
-            "user": {
-              "name": "John Doe",
-              "metadata": {
-                "hobbies": ["fishing", "hiking", "camping"],
-                "favoriteColor": "blue"
-              },
-              "joinedAt": {
-                "~~codeyam-code~~": "new Date(Date.now() - 3 * 24 * 60 * 60 * 1000).toISOString()"
-              }  
-            }
-          }
-        }
-      }
+      "mockData": { ... },
+      "argumentsData": [ ... ]
     }
   }
 }
 \`\`\`
 
-Keep in mind the above pattern is also valid for argumentsData.
-
-All code should be written in JavaScript. It will run in a node environment (not the browser) with no reference to external libraries. It will essentially be run in a sandboxed environment. Do not reference any external libraries in the code.
-
-With argumentsData you may also need to return a "children" argument. "children" can either be a string or a jsx element.
-
-If you want to return a jsx element you would return something like this:
-
-\`\`\`
+If existing data is sufficient (no changes needed):
+\`\`\`json
 {
   "scenarioData": {
-    "scenarioName": ${scenarioName},
-    "data": {
-      "argumentsData": [
-        {
-          "children": {
-            "~~codeyam-jsx~~": "<div>Click Me!</div>"
-          }
-        }
-      ]
-    }
+    "scenarioName": "${scenarioName}",
+    "data": {}
   }
 }
 \`\`\`
 
-The "~~codeyam-jsx~~" key in a "children" prop will be rendered directly to the code as a jsx element, not a string. Only return basic elements like "<div>".
-
-Do not import or reference any libraries in this code. No external libraries will be imported.
-
-If either mockData or argumentsData is empty you can return an empty object for mockData ("{}") or empty array for argumentsData ("[]"). 
-
-If an object inside of mockData or argumentsData is intended to not exist you can set it to null.
-
-Never use "~~codeyam-code~~" or "~~codeyam-jsx~~" as a partial key in the response. Even if the key looks like it should have a relative date or code. "~~codeyam-code~~" and "~~codeyam-jsx~~" are only used as independent keys used to mark values that are code.
-
-## Common Mistakes
-
-- Do not use the term undefined in the response. If something is missing leave it out or use null.
-- Leave out error data (e.g. a data attribute labeled as "error"), especially when it is in a data structure that has success data as well. Only include the success data and simply leave out the error data. Error data is usually labeled as "error" in the structure. Leave it out entirely.
-- Do not reference data in the response (e.g. if there was a "posts" field you can not say "posts[0]" elsewhere in the response - you need to duplicate the data). Unfortunately all data must be written out directly in the response.
-- Ensure each scenario in the response matches the full scenario name, commas and all, in the scenarios provided.
-- Do not throw errors from this data in any manner. Simple leave out any error data.
-- If the data structure contains a type that is a "date" then use ~~codeyam-code~~ to generate a dynamic timestamp or date. Do not hard-code dates unless it needs to be a very specific date. Otherwise it should be a relative, dynamic date.
-- The response must be valid JSON. Do not include raw code in the response.
+## Rules
+- Valid JSON only—no raw code outside markers
+- No \`undefined\`—use \`null\` or omit
+- No data references (can't use \`posts[0]\` elsewhere—duplicate the value)
+- Scenario name must match exactly: "${scenarioName}"
+- Empty mockData: \`{}\`, empty argumentsData: \`[]\`
 `;
+};
 
 const generateChangesIncompleteSystemMessage = (
   scenarioName: string,