@codeyam/codeyam-cli 0.1.0-staging.1 → 0.1.0-staging.1669d45

package/analyzer-template/packages/ai/src/lib/dataStructure/helpers/uniqueIdUtils.ts

@@ -0,0 +1,113 @@
+/**
+ * UniqueIdUtils
+ *
+ * Utility functions for creating unique identifiers and deduplicating
+ * scope variables in the ScopeDataStructure analysis.
+ *
+ * ## Why Unique IDs Matter
+ *
+ * The analysis tracks data flow across many scopes and paths. When building
+ * equivalency chains or schemas, we need to:
+ * - Detect cycles (have we seen this scope+path+value before?)
+ * - Deduplicate results (don't report the same equivalency twice)
+ * - Index efficiently (O(1) lookups in large datasets)
+ *
+ * ## Key Format
+ *
+ * The unique ID format is `scopeNodeName::schemaPath[::value]`:
+ * - `myFunc::user.id` - Scope+path without type value
+ * - `myFunc::user.id::string` - Full tuple including type
+ *
+ * The `::` delimiter is chosen because:
+ * - Scope names never contain `::`
+ * - Schema paths use `.` and `[]` but not `::`
+ * - Type values may contain `:` (e.g., `union::type`) but only as the last part
+ *
+ * ## Performance
+ *
+ * `uniqueScopeAndPaths` uses O(n) Set-based deduplication instead of O(n²)
+ * array comparisons. This matters when processing thousands of equivalencies.
+ *
+ * ## Related Modules
+ *
+ * - `VisitedTracker.ts` - Uses similar key format for cycle detection
+ * - `ScopeDataStructure.equivalencyDatabase` - Indexed by these unique IDs
+ */
+
+/**
+ * Interface for items that can be deduplicated by scope and path.
+ * Matches the ScopeVariable interface's required fields.
+ */
+export interface ScopeAndPath {
+  scopeNodeName: string;
+  schemaPath: string;
+}
+
+/**
+ * Creates a unique identifier string from scope, path, and optional value.
+ * Used for tracking visited combinations and equivalency chains.
+ *
+ * @example
+ * uniqueId({ scopeNodeName: 'myFunc', schemaPath: 'user.id' }) // 'myFunc::user.id'
+ * uniqueId({ scopeNodeName: 'myFunc', schemaPath: 'user.id', value: 'string' }) // 'myFunc::user.id::string'
+ */
+export function uniqueId({
+  scopeNodeName,
+  schemaPath,
+  value,
+}: {
+  scopeNodeName: string;
+  schemaPath: string;
+  value?: string;
+}): string {
+  const parts = [scopeNodeName, schemaPath, value].filter(Boolean);
+  return parts.join('::');
+}
+
+/**
+ * Removes duplicate scope variables from an array, keeping only the first occurrence
+ * of each unique scopeNodeName + schemaPath combination.
+ *
+ * This is a type-preserving version of uniqueScopeAndPaths that returns the full
+ * ScopeVariable objects (with id and equivalencyReason).
+ *
+ * @param scopeVariables - Array of scope variables to deduplicate
+ * @returns Deduplicated array preserving original type
+ */
+export function uniqueScopeVariables<T extends ScopeAndPath>(
+  scopeVariables: T[],
+): T[] {
+  return uniqueScopeAndPaths(scopeVariables);
+}
+
+/**
+ * Removes duplicates from an array of objects with scopeNodeName and schemaPath.
+ * Uses O(n) Set-based deduplication for performance.
+ *
+ * @param scopeVariables - Array of objects to deduplicate
+ * @returns Deduplicated array preserving original type
+ *
+ * @example
+ * uniqueScopeAndPaths([
+ *   { scopeNodeName: 'a', schemaPath: 'x' },
+ *   { scopeNodeName: 'a', schemaPath: 'x' },
+ *   { scopeNodeName: 'b', schemaPath: 'y' },
+ * ])
+ * // Returns: [{ scopeNodeName: 'a', schemaPath: 'x' }, { scopeNodeName: 'b', schemaPath: 'y' }]
+ */
+export function uniqueScopeAndPaths<T extends ScopeAndPath>(
+  scopeVariables: T[] | undefined | null,
+): T[] {
+  if (!scopeVariables || scopeVariables.length === 0) return [];
+
+  // Optimize from O(n²) to O(n) using Set for deduplication
+  const seen = new Set<string>();
+  return scopeVariables.filter((varItem) => {
+    const key = `${varItem.scopeNodeName}::${varItem.schemaPath}`;
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
+}

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

@@ -0,0 +1,30 @@
+export default function deepEqual(obj1: unknown, obj2: unknown): boolean {
+  // Handle primitive types and null/undefined
+  if (obj1 === obj2) return true;
+  if (obj1 == null || obj2 == null) return false;
+  if (typeof obj1 !== 'object' || typeof obj2 !== 'object') return false;
+
+  // Handle Date objects
+  if (obj1 instanceof Date && obj2 instanceof Date) {
+    return obj1.getTime() === obj2.getTime();
+  }
+
+  // Handle Array objects
+  if (Array.isArray(obj1) && Array.isArray(obj2)) {
+    if (obj1.length !== obj2.length) return false;
+    return obj1.every((item, index) => deepEqual(item, obj2[index]));
+  }
+
+  // Handle regular objects
+  const keys1 = Object.keys(obj1);
+  const keys2 = Object.keys(obj2);
+
+  if (keys1.length !== keys2.length) return false;
+
+  return keys1.every((key) => {
+    if (!Object.prototype.hasOwnProperty.call(obj2, key)) return false;
+    const obj1AsAny = obj1 as any;
+    const obj2AsAny = obj2 as any;
+    return deepEqual(obj1AsAny[key], obj2AsAny[key]);
+  });
+}

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

@@ -25,8 +25,7 @@ export default async function generateChangesEntityDocumentation({
 
   const { completion: documentation, stats } = await completionCall({
     type: 'entityDocumentation',
-    systemMessage:
-      'You are an expert coder and educator. You think a lot about how people can understand new things, recognizing that it is a mixture of direct facts and numerous examples from different perspectives.',
+    systemMessage: SYSTEM_MESSAGE,
     prompt,
     model,
     jsonResponse: false,
@@ -62,3 +61,22 @@ export default async function generateChangesEntityDocumentation({
 
   return { documentation, llmCall };
 }
+
+const SYSTEM_MESSAGE = `You are a technical documentation writer updating existing documentation after code changes.
+
+## When to Update
+- If existing documentation is still accurate: respond with exactly "No changes needed"
+- If code changed significantly: provide updated documentation
+
+## Style
+- Be concise—use bullets, not paragraphs
+- Provide diverse examples (no repetitive variations)
+- In Overview, describe intent directly without mentioning the function name
+
+## Required Sections (when updating)
+Return documentation with exactly these markdown headers:
+- ## Overview
+- ## Inputs
+- ## Output
+- ## Examples
+`;

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

@@ -16,6 +16,8 @@ import type {
 import { LlmCall } from '~codeyam/types';
 import validateJson from './validateJson';
 import checkAllAttributes from './checkAllAttributes';
+import convertNullToUndefinedBySchema from './dataStructure/helpers/convertNullToUndefinedBySchema';
+import deepEqual from './deepEqual';
 import { awsLog } from '~codeyam/utils';
 import { AI, parseJsonSafe } from '~codeyam/ai';
 
@@ -59,12 +61,14 @@ async function generateChangesDataForScenario({
   llmCalls: LlmCall[];
 }> {
   if (
-    structure === existingStructure &&
-    scenario.metadata.keyAttributeInstructions ===
-      existingScenario.metadata.keyAttributeInstructions
+    deepEqual(structure, existingStructure) &&
+    deepEqual(
+      scenario.metadata?.coveredFlows,
+      existingScenario?.metadata?.coveredFlows,
+    )
   ) {
     console.log(
-      "CodeYam: No changes in scenario's structure or keyAttributeInstructions - returning existing scenario data",
+      "CodeYam: No changes in scenario's structure or coveredFlows - returning existing scenario data",
       {
         analysisId: scenario.analysisId,
         scenarioId: scenario.id,
@@ -95,6 +99,7 @@ async function generateChangesDataForScenario({
       prompt = generateEntityScenarioDataGenerator(
         structure,
         scenario,
+        undefined, // executionFlows - not available in changes context
         defaultScenarioData,
         incompleteResponse,
       );
@@ -219,8 +224,8 @@ async function generateChangesDataForScenario({
     if (!Array.isArray(argumentsData)) {
       argumentsData = [];
     }
-    fullScenarioData.data.argumentsData = argumentsData.map((arg) =>
-      checkAllAttributes(arg),
+    fullScenarioData.data.argumentsData = argumentsData.map(
+      (arg) => checkAllAttributes(arg) as { [key: string]: unknown },
     );
 
     if (structure.dataForMocks && !fullScenarioData.data.mockData) {
@@ -232,7 +237,28 @@ async function generateChangesDataForScenario({
     }
     fullScenarioData.data.mockData = checkAllAttributes(
       fullScenarioData.data.mockData,
-    );
+    ) as { [key: string]: unknown };
+
+    // Convert null values to undefined based on schema type constraints.
+    // LLM uses null for "no value" (JSON doesn't support undefined), but TypeScript
+    // types like "string | undefined" don't accept null. This converts null→undefined
+    // for fields typed as "T | undefined" (but preserves null for "T | null").
+    if (structure.dataForMocks && fullScenarioData.data.mockData) {
+      convertNullToUndefinedBySchema(
+        fullScenarioData.data.mockData,
+        structure.dataForMocks,
+      );
+    }
+    if (structure.arguments && fullScenarioData.data.argumentsData) {
+      for (let i = 0; i < fullScenarioData.data.argumentsData.length; i++) {
+        if (structure.arguments[i]) {
+          convertNullToUndefinedBySchema(
+            fullScenarioData.data.argumentsData[i],
+            structure.arguments[i],
+          );
+        }
+      }
+    }
 
     return {
       llmCalls: [{ name: scenario.name, id: llmCall.id }],
@@ -322,187 +348,127 @@ 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 and key attributes set to null or undefined)
+- 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
+
+## CRITICAL: Preserve Exact Structure
+Your response MUST mirror the EXACT nested structure provided in mockData Structure.
+- Do NOT reorganize, split, or create duplicate keys
+- The hierarchy of nested objects must match exactly what was provided
+- Only change the leaf VALUES (replacing type descriptions like "string" with actual data like "hello")
+- Arrays should have 3-5 items to provide realistic test data variety
+
+**Example** - if given this structure:
+\`\`\`json
 {
-  "scenarioData": {
-    "scenarioName: "${scenarioName}",
-    "data": {}
+  "createClient()": {
+    "from(\\"users\\")": {
+      "select(\\"*\\")": { "data": [{ "id": "string", "name": "string" }] },
+      "delete()": { "eq(\\"id\\", id)": {} }
+    }
   }
 }
 \`\`\`
 
-## Example Response
-
+Return ONE \`from("users")\` key containing BOTH \`select("*")\` and \`delete()\`:
+\`\`\`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!"        
-        }      
-      ]        
+  "createClient()": {
+    "from(\\"users\\")": {
+      "select(\\"*\\")": { "data": [{ "id": "user-1", "name": "Alice" }, { "id": "user-2", "name": "Bob" }] },
+      "delete()": { "eq(\\"id\\", \\"user-1\\")": {} }
     }
   }
 }
+\`\`\`
 
-## scenarioData
+**WRONG** - do NOT create duplicate keys like this:
+\`\`\`json
+{
+  "createClient()": {
+    "from(\\"users\\")": { "select(\\"*\\")": { ... } },
+    "from(\\"users\\")": { "delete()": { ... } }
+  }
+}
+\`\`\`
 
-You will return a JSON object called scenarioData containing the name and data for this scenario.
+## Special Markers
 
-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.
+### 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).
 
-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:
+### JSX Children (\`~~codeyam-jsx~~\`)
+\`\`\`json
+{ "children": { "~~codeyam-jsx~~": "<div>Hello</div>" } }
+\`\`\`
+Use simple elements only (\`<div>\`, \`<span>\`). No custom components.
 
+### Functions (\`~~codeyam-code~~\`)
+\`\`\`json
+{ "onClick": { "~~codeyam-code~~": "() => console.log('clicked')" } }
 \`\`\`
+
+## Mock Data Keys
+Preserve keys exactly as written in the structure. There are two formats:
+- Standard function calls: \`"useUser()"\`, \`"from().select()"\`
+- Variable-qualified calls (for multiple calls to the same function): \`"entityDiffFetcher <- useFetcher"\`
+  This reads as "entityDiffFetcher receives from useFetcher". Each variable gets distinct mock data.
+
+## Response Format
+\`\`\`json
 {
   "scenarioData": {
-    "scenarioName": ${scenarioName},
+    "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,