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

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

@@ -0,0 +1,235 @@
+/**
+ * VisitedTracker
+ *
+ * Manages visited state tracking for the ScopeDataStructure analysis.
+ * Prevents infinite loops and redundant processing by tracking which
+ * scope/path/value combinations have already been processed.
+ *
+ * ## Why This Exists
+ *
+ * The schema building process recursively follows equivalencies between
+ * data paths. Without cycle detection, circular references like:
+ *   `user.profile` → `currentUser` → `user.profile`
+ * would cause infinite loops.
+ *
+ * ## Two Tracking Modes
+ *
+ * ### 1. Global Visited (scope::path::value)
+ * Fine-grained deduplication for `addToSchema()`. Tracks the complete
+ * tuple so the same path can be visited with different type values.
+ *
+ * Example: `myFunc::user.id::string` and `myFunc::user.id::number`
+ * are tracked separately, allowing both types to be recorded.
+ *
+ * ### 2. Complex Source Visited (scope::path)
+ * Coarser deduplication for `addComplexSourcePathVariables()`. Ignores
+ * the type value because complex source processing should happen once
+ * per path regardless of type.
+ *
+ * ## Lifecycle
+ *
+ * - Global visited is **reset** at the start of `captureCompleteSchema()`
+ *   to allow re-processing in the schema building phase.
+ * - Complex source visited is **never reset** during normal operation.
+ *
+ * ## Related Modules
+ *
+ * - `ScopeDataStructure.addToSchema()` - Primary consumer of global visited
+ * - `ScopeDataStructure.addComplexSourcePathVariables()` - Uses complex source visited
+ */
+
+/**
+ * Tracks visited state to prevent infinite loops during schema building.
+ */
+export class VisitedTracker {
+  /**
+   * Fine-grained visited tracking using scope::path::value.
+   * Used by addToSchema to skip already-processed combinations.
+   */
+  private globalVisited: Set<string> = new Set();
+
+  /**
+   * Coarser visited tracking using scope::path only (without value).
+   * Used by addComplexSourcePathVariables to allow each unique
+   * scope+path combo to be processed once, regardless of value.
+   */
+  private complexSourceVisited: Set<string> = new Set();
+
+  /**
+   * Creates a unique key for global visited tracking.
+   * @param scopeNodeName - Name of the scope
+   * @param path - Schema path
+   * @param value - Type value
+   */
+  private makeGlobalKey(
+    scopeNodeName: string,
+    path: string,
+    value: string,
+  ): string {
+    return `${scopeNodeName}::${path}::${value}`;
+  }
+
+  /**
+   * Creates a unique key for complex source visited tracking.
+   * @param scopeNodeName - Name of the scope
+   * @param path - Schema path
+   */
+  private makeComplexKey(scopeNodeName: string, path: string): string {
+    return `${scopeNodeName}::${path}`;
+  }
+
+  /**
+   * Checks if a scope/path/value combination has been globally visited.
+   * Does NOT mark it as visited - use markGlobalVisited for that.
+   *
+   * @returns true if already visited
+   */
+  hasGlobalVisited(
+    scopeNodeName: string,
+    path: string,
+    value: string,
+  ): boolean {
+    return this.globalVisited.has(
+      this.makeGlobalKey(scopeNodeName, path, value),
+    );
+  }
+
+  /**
+   * Marks a scope/path/value combination as globally visited.
+   */
+  markGlobalVisited(scopeNodeName: string, path: string, value: string): void {
+    this.globalVisited.add(this.makeGlobalKey(scopeNodeName, path, value));
+  }
+
+  /**
+   * Checks and marks a scope/path/value combination as globally visited.
+   * This is a convenience method that combines check and mark.
+   *
+   * @returns true if was already visited (should skip processing)
+   */
+  checkAndMarkGlobalVisited(
+    scopeNodeName: string,
+    path: string,
+    value: string,
+  ): boolean {
+    const key = this.makeGlobalKey(scopeNodeName, path, value);
+    if (this.globalVisited.has(key)) {
+      return true; // Already visited
+    }
+    this.globalVisited.add(key);
+    return false; // Not visited, now marked
+  }
+
+  /**
+   * Checks if a scope/path combination has been visited for complex sources.
+   * Does NOT mark it as visited - use markComplexSourceVisited for that.
+   *
+   * @returns true if already visited
+   */
+  hasComplexSourceVisited(scopeNodeName: string, path: string): boolean {
+    return this.complexSourceVisited.has(
+      this.makeComplexKey(scopeNodeName, path),
+    );
+  }
+
+  /**
+   * Marks a scope/path combination as visited for complex sources.
+   */
+  markComplexSourceVisited(scopeNodeName: string, path: string): void {
+    this.complexSourceVisited.add(this.makeComplexKey(scopeNodeName, path));
+  }
+
+  /**
+   * Checks and marks a scope/path combination as visited for complex sources.
+   * This is a convenience method that combines check and mark.
+   *
+   * @returns true if was already visited (should skip processing)
+   */
+  checkAndMarkComplexSourceVisited(
+    scopeNodeName: string,
+    path: string,
+  ): boolean {
+    const key = this.makeComplexKey(scopeNodeName, path);
+    if (this.complexSourceVisited.has(key)) {
+      return true; // Already visited
+    }
+    this.complexSourceVisited.add(key);
+    return false; // Not visited, now marked
+  }
+
+  /**
+   * Resets the global visited set.
+   * Called at the start of captureCompleteSchema() to allow
+   * re-processing in the second phase.
+   */
+  resetGlobalVisited(): void {
+    this.globalVisited.clear();
+  }
+
+  /**
+   * Resets the complex source visited set.
+   * Note: In the original code, this was never reset.
+   */
+  resetComplexSourceVisited(): void {
+    this.complexSourceVisited.clear();
+  }
+
+  /**
+   * Resets all visited tracking.
+   */
+  resetAll(): void {
+    this.globalVisited.clear();
+    this.complexSourceVisited.clear();
+  }
+
+  /**
+   * Returns statistics about the visited sets for debugging/monitoring.
+   */
+  getStats(): { globalVisited: number; complexSourceVisited: number } {
+    return {
+      globalVisited: this.globalVisited.size,
+      complexSourceVisited: this.complexSourceVisited.size,
+    };
+  }
+
+  /**
+   * Checks if ANY variant of a scope/path was ever visited (ignores value).
+   * Useful for debugging to see if a path was processed at all.
+   *
+   * @returns true if any variant of this scope/path was visited
+   */
+  wasVisited(scopeNodeName: string, path: string): boolean {
+    const prefix = `${scopeNodeName}::${path}::`;
+    for (const key of this.globalVisited) {
+      if (key.startsWith(prefix)) {
+        return true;
+      }
+    }
+    return this.hasComplexSourceVisited(scopeNodeName, path);
+  }
+
+  /**
+   * Gets all visited entries for a scope (for debugging).
+   * Returns an array of {path, value} objects.
+   */
+  getVisitedForScope(
+    scopeNodeName: string,
+  ): Array<{ path: string; value: string }> {
+    const prefix = `${scopeNodeName}::`;
+    const results: Array<{ path: string; value: string }> = [];
+
+    for (const key of this.globalVisited) {
+      if (key.startsWith(prefix)) {
+        const parts = key.slice(prefix.length).split('::');
+        if (parts.length >= 2) {
+          results.push({
+            path: parts.slice(0, -1).join('::'), // Everything except last part
+            value: parts[parts.length - 1], // Last part is value
+          });
+        }
+      }
+    }
+
+    return results;
+  }
+}

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

@@ -355,9 +355,11 @@ export function fillInDirectSchemaGapsAndUnknowns({
 
           // Don't set to 'function' if this is a promise method on an async function
           // (we want the awaited value, not the promise)
+          // Also don't overwrite 'array' - the function might return an array (e.g., getAll())
           if (
             schema[functionReturnValuePath] &&
             schema[functionReturnValuePath] !== 'function' &&
+            schema[functionReturnValuePath] !== 'array' &&
             !(isPromiseMethod && isPreviousAsync)
           ) {
             schema[functionReturnValuePath] = 'function';
@@ -408,17 +410,26 @@ function checkIfObjectOrFunction(path: string, schema: ScopeNode['schema']) {
   }
 }
 
-// Methods that are ambiguous - used on both arrays and non-arrays (e.g., router.push, history.pop)
+// Methods that are ambiguous - used on both arrays and non-arrays
+// These methods exist on arrays but also on Map, Set, Headers, FormData, URLSearchParams, etc.
 // Don't infer array type from these alone without additional evidence
-const AMBIGUOUS_ARRAY_METHODS = new Set(['push', 'pop']);
+const AMBIGUOUS_ARRAY_METHODS = new Set([
+  'push',
+  'pop',
+  'entries',
+  'keys',
+  'values',
+  'forEach',
+]);
 
 // Methods that are strongly indicative of arrays - only arrays have these
+// Note: entries, keys, values, forEach are NOT in this list because they also exist
+// on Map, Set, Headers, FormData, URLSearchParams, and other iterable types
 const STRONG_ARRAY_METHODS = new Set([
   'map',
   'filter',
   'reduce',
   'reduceRight',
-  'forEach',
   'every',
   'some',
   'find',
@@ -429,9 +440,6 @@ const STRONG_ARRAY_METHODS = new Set([
   'flatMap',
   'fill',
   'copyWithin',
-  'entries',
-  'keys',
-  'values',
   'toReversed',
   'toSorted',
   'toSpliced',

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

@@ -0,0 +1,70 @@
+/**
+ * selectBestValue
+ *
+ * Selects the most specific type value from two candidates.
+ * Prefers more specific types over 'unknown' values.
+ *
+ * ## Context
+ *
+ * During schema building, the same path may have type information from
+ * multiple sources (e.g., from a return statement and from a function call).
+ * When merging these, we want to keep the most specific type.
+ *
+ * "Specific" means:
+ * - `'string'` is more specific than `'unknown'`
+ * - `'string'` is more specific than `'unknown|string'`
+ * - `'string|number'` is equal specificity to `'number|string'`
+ *
+ * ## Selection Rules
+ *
+ * 1. If value1 exists and is not 'unknown', use value1
+ * 2. If value2 exists and is more specific (not 'unknown'), prefer value2
+ * 3. Otherwise use the first available value, or 'unknown' as default
+ *
+ * ## Where Used
+ *
+ * - `propagateSourceAndUsageEquivalencies.equateSchema()` - Merging schemas
+ * - `getReturnValue()` - Combining return type information
+ *
+ * ## Related Modules
+ *
+ * - `ensureSchemaConsistency.ts` - Also deals with type merging
+ * - `fillInSchemaGapsAndUnknowns.ts` - Fills in missing types after schema building
+ */
+
+/**
+ * Selects the best (most specific) value between two type candidates.
+ *
+ * @param value1 - Primary value (preferred if specific)
+ * @param value2 - Secondary value (used if value1 is 'unknown')
+ * @param defaultValue - Default when both are undefined (defaults to 'unknown')
+ * @returns The most specific type value
+ *
+ * @example
+ * selectBestValue('string', 'number') // 'string' - value1 is specific
+ * selectBestValue('unknown', 'string') // 'string' - value2 is more specific
+ * selectBestValue(undefined, 'number') // 'number' - value1 undefined
+ * selectBestValue(undefined, undefined) // 'unknown' - default
+ * selectBestValue('unknown|string', 'string') // 'string' - value2 has no unknown
+ */
+export default function selectBestValue(
+  value1: string | undefined,
+  value2: string | undefined,
+  defaultValue = 'unknown',
+): string {
+  let bestValue = value1 ?? value2 ?? defaultValue;
+
+  // Prefer value2 if:
+  // - value2 exists AND
+  // - bestValue is 'unknown' and value2 is not, OR
+  // - bestValue contains 'unknown' and value2 doesn't
+  if (
+    value2 &&
+    ((bestValue === 'unknown' && value2 !== 'unknown') ||
+      (bestValue.includes('unknown') && !value2.includes('unknown')))
+  ) {
+    bestValue = value2;
+  }
+
+  return bestValue;
+}

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

@@ -70,6 +70,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
+`;