@codeyam/codeyam-cli 0.1.0-staging.09652b8 → 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';

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

@@ -57,8 +57,8 @@ export default async function generateEntityKeyAttributes({
     staticAnalysisContext,
   });
 
-  console.info('Generated prompt for generateEntityKeyAttributes:');
-  console.info(prompt);
+  console.log('Generated prompt for generateEntityKeyAttributes:');
+  console.log(prompt);
 
   const response = await completionCall({
     type: `generateEntityKeyAttributes`,
@@ -167,15 +167,26 @@ NOT key attributes:
 - Values that would cause errors if changed
 - Guard clauses that render literally nothing
 
-Note: A conditional that shows a different UI state (e.g., loading screen, redirect message) IS significant—include it.
+## 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[]\`).
+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[]\`).
+
+## Valid Value Options
+
+- For \`validValueOptions\`, include boundary/extreme values that trigger different behavior 
+- 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
 
-For \`validValueOptions\`, include boundary/extreme values that trigger different behavior—but NOT values that would cause errors.
+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
 {
@@ -183,7 +194,7 @@ For \`validValueOptions\`, include boundary/extreme values that trigger differen
     {
       "fullPath": "signature[0].user",
       "description": "Controls whether the main form or redirect screen displays",
-      "validValueOptions": ["truthy user object", "null/undefined"]
+      "validValueOptions": ["an empty object {}", "null/undefined"]
     }
   ]
 }
@@ -205,13 +216,26 @@ NOT key attributes:
 - 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[]\`).
+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[]\`).
+
+## Valid Value Options
+
+- For \`validValueOptions\`, include boundary/extreme values that trigger different behavior 
+- 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
 
-For \`validValueOptions\`, include boundary/extreme values that trigger different behavior—but NOT values that would cause errors.
+List all key attributes in order from most impactful to least impactful using the following format:
 
 \`\`\`json
 {

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

@@ -259,8 +259,16 @@ function getLiteralValue(expr: ts.Expression): string | undefined {
 /**
  * Format conditional usages into a string for the LLM prompt
  */
+/**
+ * Interface for conditional usages that may have source tracing information.
+ * This is a superset of ConditionalUsage that includes optional sourceDataPath.
+ */
+interface EnrichedConditionalUsageInput extends ConditionalUsage {
+  sourceDataPath?: string;
+}
+
 export function formatConditionalUsagesForPrompt(
-  conditionalUsages: Record<string, ConditionalUsage[]>,
+  conditionalUsages: Record<string, EnrichedConditionalUsageInput[]>,
 ): string {
   const entries = Object.entries(conditionalUsages);
   if (entries.length === 0) {
@@ -270,7 +278,7 @@ export function formatConditionalUsagesForPrompt(
   const lines: string[] = [
     '\n## Static Analysis: Attributes Used in Conditionals',
     '',
-    'The following attributes were found to be used in conditional statements, making them potential key attributes:',
+    'The following attributes were found to be used in conditional statements, making them very likely key attributes:',
     '',
   ];
 
@@ -281,20 +289,30 @@ export function formatConditionalUsagesForPrompt(
       .flatMap((u) => u.comparedValues || []);
     const uniqueValues = [...new Set(allComparedValues)];
 
-    let description = `- "${path}": `;
+    // Get the source data path if available (traced back to data source)
+    const sourceDataPath = usages.find((u) => u.sourceDataPath)?.sourceDataPath;
+
+    let description = `- "${path}"`;
+
+    // If we have a source data path, show that the local variable derives from a data source
+    if (sourceDataPath) {
+      description += `\n    - Source: "${sourceDataPath}"`;
+    }
+
+    description += '\n    - ';
 
     if (uniqueTypes.includes('switch')) {
-      description += 'used as switch discriminant';
+      description += 'Used as switch discriminant';
       if (uniqueValues.length > 0) {
         description += ` with cases: ${uniqueValues.map((v) => `"${v}"`).join(', ')}`;
       }
     } else if (uniqueTypes.includes('comparison')) {
-      description += 'used in comparison';
+      description += 'Used in comparison';
       if (uniqueValues.length > 0) {
         description += ` against values: ${uniqueValues.map((v) => `"${v}"`).join(', ')}`;
       }
     } else {
-      description += 'used in truthiness check (presence/absence matters)';
+      description += 'Used in truthiness check (presence/absence matters)';
     }
 
     lines.push(description);
@@ -304,6 +322,9 @@ export function formatConditionalUsagesForPrompt(
   lines.push(
     'Consider these attributes as candidates for key attributes, especially those with specific comparison values.',
   );
+  lines.push(
+    'When a local variable derives from a data source, the data source is the key attribute.',
+  );
 
   return lines.join('\n');
 }

package/analyzer-template/packages/ai/src/lib/promptGenerators/gatherAttributesMap.ts

@@ -5,9 +5,44 @@ import {
   splitOutsideParenthesesAndArrays,
 } from '../splitOutsideParentheses';
 
+/**
+ * Checks if a bracket-only path is a valid string key access (not just an index).
+ * Valid: ['*'], ['someKey'] - string key access
+ * Invalid: [0], [1] - numeric index only (meaningless without parent path)
+ */
+function isValidBracketStringKey(attribute: string): boolean {
+  // Match ['string'] or ["string"] patterns
+  return /^\[['"][^'"]+['"]\]$/.test(attribute);
+}
+
+/**
+ * Extracts the string key from a bracket notation like ['*'] or ["key"]
+ * Returns the key without quotes and brackets, e.g., '*' or 'key'
+ */
+function extractBracketStringKey(attribute: string): string | null {
+  const match = attribute.match(/^\[['"]([^'"]+)['"]\]$/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Normalizes a path by extracting string keys from bracket notation.
+ * If the path is a single bracket string key like ['*'], returns the key ('*').
+ * Otherwise returns the path unchanged.
+ */
+function normalizePathForInternalUse(path: string): string {
+  const extracted = extractBracketStringKey(path);
+  return extracted !== null ? extracted : path;
+}
+
 function validAttribute(attribute: string) {
-  if (!attribute || attribute.length === 0 || attribute.startsWith('['))
-    return false;
+  if (!attribute || attribute.length === 0) return false;
+
+  // Allow string-key bracket access like ['*'] or ['someKey']
+  // These are valid data paths from objects with dynamic/special keys
+  if (attribute.startsWith('[')) {
+    return isValidBracketStringKey(attribute);
+  }
+
   const attributeParts = splitOutsideParenthesesAndArrays(attribute);
   if (
     attributeParts.some((part) =>
@@ -153,8 +188,11 @@ export function gatherAttributesMap(
           // Fall through to normal processing for other return value properties
         }
 
-        const relativePath = joinParenthesesAndArrays(pathParts.slice(2));
-        if (!validAttribute(relativePath)) continue;
+        const rawRelativePath = joinParenthesesAndArrays(pathParts.slice(2));
+        if (!validAttribute(rawRelativePath)) continue;
+
+        // Normalize the path for internal use (e.g., ['*'] -> '*')
+        const relativePath = normalizePathForInternalUse(rawRelativePath);
 
         attributesMap[relativePath] = returnValueDataStructure[path];
         associationMap[reverse ? relativePath : path] = reverse