@codeyam/codeyam-cli 0.1.0-staging.1 → 0.1.0-staging.596f0eb

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/gatherRelevantDependentKeyAttributes.ts

@@ -1,4 +1,9 @@
-import { Entity, ReadonlyAnalysis, ReadonlyAnalysisMap } from '~codeyam/types';
+import {
+  DataStructure,
+  Entity,
+  ReadonlyAnalysis,
+  ReadonlyAnalysisMap,
+} from '~codeyam/types';
 import {
   joinParenthesesAndArrays,
   splitOutsideParenthesesAndArrays,
@@ -7,6 +12,7 @@ import { gatherAttributesMap } from './promptGenerators/gatherAttributesMap';
 
 export default function gatherRelevantDependentKeyAttributes(
   entity: Pick<Entity, 'name' | 'metadata'>,
+  mergedDataStructure: Omit<DataStructure, 'equivalentSignatureVariables'>,
   dependentAnalyses: ReadonlyAnalysisMap,
 ) {
   // console.info(
@@ -52,10 +58,16 @@ export default function gatherRelevantDependentKeyAttributes(
   //   ),
   // );
 
-  const { associationMap } = gatherAttributesMap(entity);
+  const isolatedDataStructure = entity.metadata?.isolatedDataStructure;
+  const equivalentSignatureVariables =
+    isolatedDataStructure?.equivalentSignatureVariables ?? {};
+  const { associationMap } = gatherAttributesMap(
+    isolatedDataStructure ?? mergedDataStructure,
+    mergedDataStructure,
+    equivalentSignatureVariables,
+  );
 
-  const dependencySchemas =
-    entity.metadata?.isolatedDataStructure?.dependencySchemas;
+  const dependencySchemas = mergedDataStructure?.dependencySchemas;
   const relevantDependentKeyAttributes: ReadonlyAnalysis['metadata']['keyAttributes'][0][] =
     [];
   Object.keys(dependentAnalyses).forEach((path) => {
@@ -70,6 +82,42 @@ export default function gatherRelevantDependentKeyAttributes(
       const signatureSchema = dependencySchema?.signatureSchema;
       if (!signatureSchema) return;
 
+      const sourceEquivalencies = dependencySchema?.sourceEquivalencies ?? {};
+
+      // If sourceEquivalencies is empty but the child has mocked imports,
+      // propagate key attributes directly since they affect the parent's visual output
+      if (Object.keys(sourceEquivalencies).length === 0) {
+        // Check both importedExports and nodeModuleImports for mocked imports
+        const importedExports =
+          dependentAnalysis.entity?.metadata?.importedExports ?? [];
+        const nodeModuleImports =
+          dependentAnalysis.entity?.metadata?.nodeModuleImports ?? {};
+
+        const hasMockedImportedExports = importedExports.some(
+          (imp: { isMocked?: boolean }) => imp.isMocked,
+        );
+        const hasMockedNodeModuleImports = Object.values(
+          nodeModuleImports,
+        ).some((imports: any[]) =>
+          imports?.some((imp: { isMocked?: boolean }) => imp.isMocked),
+        );
+
+        const childHasMockedImports =
+          hasMockedImportedExports || hasMockedNodeModuleImports;
+
+        if (childHasMockedImports) {
+          for (const dependentKeyAttribute of dependentKeyAtttributes) {
+            relevantDependentKeyAttributes.push({
+              ...dependentKeyAttribute,
+              dependentEntityName: entityName,
+              originalEntityName: entityName,
+              filePath: path,
+            } as any);
+          }
+        }
+        return;
+      }
+
       for (const dependentKeyAttribute of dependentKeyAtttributes) {
         const dependentKeyAttributeExternalPathParts =
           splitOutsideParenthesesAndArrays(dependentKeyAttribute.externalPath);

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/generateChangesEntityKeyAttributes.ts

@@ -29,8 +29,17 @@ export default async function generateChangesEntityKeyAttributes({
     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(entity, true);
+    gatherAttributesMap(
+      isolatedDataStructure ?? mergedDataStructure,
+      mergedDataStructure,
+      equivalentSignatureVariables,
+      true,
+    );
 
   const prompt = generateEntityKeyAttributesGenerator({
     code: entity.code,
@@ -102,6 +111,9 @@ export default async function generateChangesEntityKeyAttributes({
       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);
@@ -138,154 +150,122 @@ export default async function generateChangesEntityKeyAttributes({
   };
 }
 
-const FRONTEND_SYSTEM_MESSAGE = `We have a frontend 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.
-
-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.
-
-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.
+const FRONTEND_SYSTEM_MESSAGE = `You are updating the key attributes for a frontend component that was recently changed.
 
-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.
+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.
 
-## Key Attribute Rules
+## Stability Rules
 
-- 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.
+- 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
 
-### Should be a key attribute
+## What Makes a Key Attribute
 
-- 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).
+A key attribute is a data path from "Attributes and Value Types" that dramatically changes how the component renders:
 
-- 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).
+- 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
 
-### Should NOT be a key attribute
+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
 
-- Changing the value of this variable will cause an error or exception to be thrown.
+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 of this variable will cause a guard clause to be triggered that results in nothing being displayed.
+## Path Format
 
-- Changing the value of this variable will cause a minor change in display that is not significant (e.g. slightly different text).
+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[]\`).
 
-- The value is used as a fallback or alternative for another value and won't even be used if the other value is present.
+## Dependencies
 
-- The value changes non-visible behavior (e.g. the href in a link or src in an image - all images sources are mocked out).
+If this key attribute is only used if one or more other attributes have specific values, include those dependencies in a \`dependencies\` array.
 
-## Instructions
+## Value Type
 
-- 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.
+Should reiterate the type of the attribute (e.g., "string", "object", "array", "boolean", etc.) based on the "Attributes and Value Types" list.
 
-## Response
+## Response Format
 
-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"
+      "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" }
       ],
-      "errorValueOptions": []
-    },
+      "valueType": "object",
+      "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?
+const BACKEND_SYSTEM_MESSAGE = `You are updating the key attributes for a backend function that was recently changed.
 
-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.
+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.
 
-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?
+## Stability Rules
 
-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.
+- 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
 
-In order to do so we want to identify the key data attributes in the code.
+## What Makes a Key Attribute
 
-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.
+A key attribute is a data path from "Attributes and Value Types" that dramatically changes the function's behavior:
 
-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.
+- 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.)
 
-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.
+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
 
-## Key Attribute Rules
+## Path Format
 
-- 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.
+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 be a key attribute
+## Dependencies
 
-- Changing the value, length (e.g. for strings or arrays), etc of this variable will dramatically impact the return value of the function.
+If this key attribute is only used if one or more other attributes have specific values, include those dependencies in a \`dependencies\` array.
 
-- 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).
+## Value Type
 
-- 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 reiterate the type of the attribute (e.g., "string", "object", "array", "boolean", etc.) based on the "Attributes and Value Types" list.
 
-### 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 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"
+      "path": "config.enabled",
+      "description": "Controls whether the main processing logic runs",
+      "dependencies": [
+        { "analysisMode": "must be 'full' for 'enabled' to have effect" }
       ],
-      "errorValueOptions": []
-    },
+      "valueType": "boolean",
+      "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.
 `;