@codeyam/codeyam-cli 0.1.0-bleeding-edge.8afd3ee

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

@@ -0,0 +1,2736 @@
+/* ScopeDataStructure
+ *
+ * The ScopeDateStructure takes the output of the ASTAnalyzer and merges
+ * all scopes to determine a complete schema for the function.
+ *
+ * It does two passes through all scopes.
+ *
+ * The first establishes equivalencies,
+ * such as implicit parent scope -> nested child scope equivalencies.
+ *
+ * The second pass follows all equivalencies to build up a complete schema at the
+ * source of the data (either the function's signature arguments or an external
+ * API call made from within the function). While following the equivalencies the
+ * second pass populates the equivalencyDatabase which tracks all equivalent values
+ * and provides easy access to determine where data comes from and where it is used
+ * to call external functions. This makes it possible to combine schemas between
+ * functions to create a complete schema for a dependency tree.
+ *
+ * There are a number of getter functions that provide easy access to signature data
+ * and return values for the function being analyzed and any function called from the
+ * function being analyzed.
+ */
+
+import { ScopeAnalysis } from '~codeyam/types';
+import {
+  joinParenthesesAndArrays,
+  splitOutsideParenthesesAndArrays,
+} from '../splitOutsideParentheses';
+import { EquivalencyManager } from './equivalencyManagers/EquivalencyManager';
+import fillInSchemaGapsAndUnknowns from './helpers/fillInSchemaGapsAndUnknowns';
+import ensureSchemaConsistency from './helpers/ensureSchemaConsistency';
+import cleanOutBoundary from '../cleanOutBoundary';
+import cleanPath from './helpers/cleanPath';
+import cleanScopeNodeName from './helpers/cleanScopeNodeName';
+import getFunctionCallRoot from './helpers/getFunctionCallRoot';
+import cleanPathOfNonTransformingFunctions from './helpers/cleanPathOfNonTransformingFunctions';
+import { arrayMethodsSet } from './helpers/cleanNonObjectFunctions';
+import type {
+  SerializableDataStructure,
+  SerializableFunctionCallInfo,
+  SerializableFunctionResult,
+  SerializableScopeVariable,
+} from '../worker/SerializableDataStructure';
+
+// import { appendFileSync } from 'node:fs';
+// function writeEquivalencyToFile(
+//   scopeNodeName: string,
+//   path: string,
+//   equivalentScopeNodeName: string,
+//   equivalentPath: string,
+//   newEquivalentPath: string,
+//   equivalencyReason: string,
+// ) {
+//   if ([
+//     'original equivalency'
+//   ].includes(equivalencyReason)) {
+//     return
+//   }
+
+//   appendFileSync('equivalencies.txt', '\n\n');
+//   appendFileSync('equivalencies.txt',
+//     JSON.stringify(
+//       {
+//         newEquivalentPath,
+//         scopeNodeName,
+//         path,
+//         equivalentScopeNodeName,
+//         equivalentPath,
+//         equivalencyReason,
+//       },
+//       null,
+//       2,
+//     ),
+//   );
+// }
+
+export interface ScopeInfo {
+  name: string;
+  text: string;
+  start: number;
+  end: number;
+  variables: string[];
+  dataStructure?: ScopeDataStructure | SerializableDataStructure;
+  childScopes: { [name: string]: ScopeInfo };
+  isStatic?: boolean;
+  isClassScope?: boolean;
+  analysis?: any;
+}
+
+export interface ScopeNode {
+  name: string;
+  tree: string[];
+  text: string;
+  analysis: ScopeAnalysis;
+  isStatic?: boolean;
+  schema: Record<string, string>;
+  equivalencies: Record<string, ScopeVariable[]>; // Trace data attributes to the source of the data
+  functionCalls: FunctionCallInfo[];
+  isFunctionDefinition: boolean;
+  instantiatedVariables?: string[]; // Variables instantiated in this scope
+  parentInstantiatedVariables?: string[]; // Variables instantiated in the parent scope that are available in this scope
+}
+
+export interface ScopeTreeNode {
+  name: string;
+  children: ScopeTreeNode[];
+}
+
+export interface ScopeVariable {
+  id: number; // Never go through the same equivalency twice
+  scopeNodeName: string;
+  schemaPath: string;
+  equivalencyReason: string;
+}
+
+export interface VariableInfo {
+  name: string;
+  equivalentTo?: ScopeVariable[];
+  schema: Record<string, string>;
+}
+
+export interface FunctionCallInfo {
+  name: string;
+  callSignature: string;
+  callScope: string;
+  schema?: Record<string, string>; // For tracking schema of external function calls
+  equivalencies?: Record<string, ScopeVariable[]>; // Trace all signature data back to original source (either root scope signature of functionCallReturnValue of another external function call)
+}
+
+export interface EquivalencyValueChainItem {
+  id: number;
+  addToSchemaId?: number;
+  source: string;
+  previousPath?: {
+    scopeNodeName: string;
+    schemaPath: string;
+    value: string;
+  };
+  currentPath?: {
+    scopeNodeName: string;
+    schemaPath: string;
+    value: string;
+  };
+  reason: string;
+  traceId?: number;
+}
+
+export interface EquivalencyDatabaseEntry {
+  id: number;
+  sourceCandidates: Pick<ScopeVariable, 'schemaPath' | 'scopeNodeName'>[];
+  usages: Pick<ScopeVariable, 'schemaPath' | 'scopeNodeName'>[];
+  intermediatesOrder: Record<string, number>;
+  complexSourceEquivalencies: Set<string>; // subsets of this equivalent path that each have different data sources (e.g. the variable analysisEntityPair has a different source for analysisEntityPair.analysis vs analysisEntityPair.entity)
+}
+
+const ROOT_SCOPE_NAME = 'root';
+
+// DEBUG: Performance metrics
+export let maxEquivalencyChainDepth = 0;
+export let addToSchemaCallCount = 0;
+export let followEquivalenciesCallCount = 0;
+export function resetScopeDataStructureMetrics() {
+  maxEquivalencyChainDepth = 0;
+  addToSchemaCallCount = 0;
+  followEquivalenciesCallCount = 0;
+}
+
+export class ScopeDataStructure {
+  debugCount = 0;
+  onlyEquivalencies = true;
+  equivalencyManagers: EquivalencyManager[] = [];
+  scopeNodes: Record<string, ScopeNode> = {};
+  scopeTree: ScopeTreeNode = { name: ROOT_SCOPE_NAME, children: [] };
+  externalFunctionCalls: FunctionCallInfo[] = [];
+  environmentVariables: string[] = [];
+  equivalencyDatabase: EquivalencyDatabaseEntry[] = [];
+
+  private lastAddToSchemaId = 0;
+  private lastEquivalencyId = 0;
+  private lastEquivalencyDatabaseId = 0;
+  private pathPartsCache: Map<string, string[]> = new Map();
+  private pathJoinCache: Map<string, string> = new Map();
+  private equivalencyDatabaseCache: Map<
+    string,
+    EquivalencyDatabaseEntry | undefined
+  > = new Map();
+  // Inverted index: maps uniqueId -> EquivalencyDatabaseEntry for O(1) lookup
+  private intermediatesOrderIndex: Map<string, EquivalencyDatabaseEntry> =
+    new Map();
+  private globalVisited: Set<string> = new Set();
+
+  constructor(
+    managers: EquivalencyManager[],
+    scopeName = ROOT_SCOPE_NAME,
+    scopeText: string,
+    scopeAnalysis: ScopeAnalysis,
+  ) {
+    this.equivalencyManagers.push(...managers);
+    this.scopeTree.name = scopeName;
+    this.addScopeAnalysis(scopeName, scopeText, scopeAnalysis);
+  }
+
+  addScopeAnalysis(
+    scopeNodeName: string,
+    scopeText: string,
+    scopeAnalysis: ScopeAnalysis,
+    parentScopeName?: string,
+    isStatic?: boolean,
+  ) {
+    try {
+      if (scopeNodeName !== this.scopeTree.name && !parentScopeName) {
+        parentScopeName = this.scopeTree.name;
+      }
+
+      let tree: any[] = [];
+      if (parentScopeName) {
+        tree = [...(this.scopeNodes[parentScopeName]?.tree ?? [])];
+        tree.push(parentScopeName);
+      }
+
+      const isFunctionDefinition =
+        scopeNodeName.includes('____cyScope') || scopeText.startsWith('(');
+
+      let scopeNode: ScopeNode = {
+        name: scopeNodeName,
+        tree,
+        text: scopeText,
+        analysis: scopeAnalysis,
+        schema: {},
+        equivalencies: {},
+        functionCalls: [],
+        isFunctionDefinition,
+        isStatic,
+      };
+
+      if (!this.scopeNodes[scopeNodeName]) {
+        this.setInstantiatedVariables(scopeNode);
+        this.scopeNodes[scopeNodeName] = scopeNode;
+        this.addToTree([...tree, scopeNodeName]);
+      } else {
+        scopeNode = this.scopeNodes[scopeNodeName];
+      }
+
+      this.determineEquivalenciesAndBuildSchema(scopeNode);
+
+      this.equivalencyManagers.forEach((manager) =>
+        manager.postProcess(scopeNode, this),
+      );
+
+      this.trackFunctionCalls(scopeNode);
+
+      // Collect environment variables from the scope analysis
+      if (scopeAnalysis.environmentVariables) {
+        scopeAnalysis.environmentVariables.forEach((envVar) => {
+          if (!this.environmentVariables.includes(envVar)) {
+            this.environmentVariables.push(envVar);
+          }
+        });
+      }
+    } catch (error) {
+      console.log(
+        'CodeYam Error: Failed to add scope analysis for scope:',
+        JSON.stringify(
+          {
+            rootScopeName: this.scopeTree.name,
+            scopeNodeName,
+            scopeNodeText: scopeText,
+            isolatedStructure: scopeAnalysis.isolatedStructure,
+            isolatedEquivalentVariables:
+              scopeAnalysis.isolatedEquivalentVariables,
+          },
+          null,
+          2,
+        ),
+      );
+      throw error;
+    }
+  }
+
+  async captureCompleteSchema() {
+    this.onlyEquivalencies = false;
+    this.equivalencyDatabase = [];
+    this.equivalencyDatabaseCache.clear(); // Clear cache when database is reset
+    this.intermediatesOrderIndex.clear(); // Clear inverted index when database is reset
+    this.globalVisited = new Set([]);
+
+    for (const externalFunctionCall of this.externalFunctionCalls) {
+      externalFunctionCall.schema = {};
+    }
+
+    // for (const scopeNode of Object.values(this.scopeNodes)) {
+    await Promise.all(
+      Object.values(this.scopeNodes).map(async (scopeNode) => {
+        scopeNode.schema = {};
+        await this.determineEquivalenciesAndBuildSchema(scopeNode);
+      }),
+    );
+    // }
+    const validExternalFacingScopeNames = new Set<string>([
+      this.scopeTree.name,
+    ]);
+    this.externalFunctionCalls = this.externalFunctionCalls.filter((efc) => {
+      const efcName = efc.name.split('<')[0];
+      for (const manager of this.equivalencyManagers) {
+        if (manager.internalFunctions.has(efcName)) {
+          return false;
+        }
+      }
+      validExternalFacingScopeNames.add(efcName);
+      return true;
+    });
+
+    for (const entry of this.equivalencyDatabase) {
+      entry.usages = entry.usages.filter(
+        (usage) =>
+          validExternalFacingScopeNames.has(
+            usage.scopeNodeName.split('<')[0],
+          ) &&
+          (usage.schemaPath.startsWith('returnValue') ||
+            usage.schemaPath.startsWith(usage.scopeNodeName.split('<')[0])) &&
+          !Array.from(arrayMethodsSet).some((method) =>
+            usage.schemaPath.includes(`.${method}(`),
+          ),
+      );
+      entry.sourceCandidates = entry.sourceCandidates.filter(
+        (candidate) =>
+          validExternalFacingScopeNames.has(
+            candidate.scopeNodeName.split('<')[0],
+          ) &&
+          (candidate.schemaPath.startsWith('signature[') ||
+            candidate.schemaPath.startsWith(
+              candidate.scopeNodeName.split('<')[0],
+            )) &&
+          !Array.from(arrayMethodsSet).some((method) =>
+            candidate.schemaPath.includes(`.${method}(`),
+          ),
+      );
+    }
+
+    this.propagateSourceAndUsageEquivalencies(
+      this.scopeNodes[this.scopeTree.name],
+    );
+
+    for (const externalFunctionCall of this.externalFunctionCalls) {
+      const t = new Date().getTime();
+      // console.info("Start Propagating", JSON.stringify({
+      //   externalFunctionCallName: externalFunctionCall.name,
+      //   // sourceEquivalencies: externalFunctionCall.sourceEquivalencies,
+      // }, null, 2));
+
+      this.propagateSourceAndUsageEquivalencies(externalFunctionCall);
+
+      const elapsedTime = new Date().getTime() - t;
+      if (elapsedTime > 100) {
+        console.warn('Long Propagation Time', {
+          externalFunctionCallName: externalFunctionCall.name,
+          time: elapsedTime,
+        });
+        // throw new Error("STOP - LONG PROPAGATION TIME")
+      }
+
+      // console.info("Done Propagating", JSON.stringify({
+      //   externalFunctionCallName: externalFunctionCall.name,
+      //   // sourceEquivalencies: externalFunctionCall.sourceEquivalencies,
+      //   // usageEquivalencies: externalFunctionCall.usageEquivalencies,
+      //   time: elapsedTime
+      // }, null, 2))
+    }
+  }
+
+  addToSchema({
+    path,
+    value,
+    scopeNode,
+    equivalencyValueChain = [],
+    traceId,
+  }: {
+    path: string;
+    value: string;
+    scopeNode: ScopeNode;
+    equivalencyValueChain?: EquivalencyValueChainItem[];
+    traceId?: number;
+  }) {
+    addToSchemaCallCount++;
+    // Track max chain depth
+    if (equivalencyValueChain.length > maxEquivalencyChainDepth) {
+      maxEquivalencyChainDepth = equivalencyValueChain.length;
+    }
+    if (!scopeNode) return;
+
+    if (!this.isValidPath(path)) {
+      if (traceId) {
+        console.info('Debug propagation: not a valid path', { path, traceId });
+      }
+      return;
+    }
+
+    if (equivalencyValueChain.length > 0) {
+      equivalencyValueChain[equivalencyValueChain.length - 1].addToSchemaId =
+        ++this.lastAddToSchemaId;
+      equivalencyValueChain[equivalencyValueChain.length - 1].currentPath = {
+        scopeNodeName: scopeNode.name,
+        schemaPath: path,
+        value,
+      };
+    }
+
+    // Use this debugging to track down an infinite loop
+    // traceId ||= 0;
+    // traceId += 1;
+    // if (traceId) {
+    //   console.info(JSON.stringify({ traceId, path, value, scopeNodeName: scopeNode.name }, null, 2));
+    // }
+    // if (traceId > 30) {
+    //   console.warn(
+    //     'HIGH TRACEID',
+    //     JSON.stringify(
+    //       {
+    //         path,
+    //         value,
+    //         scopeNodeName: scopeNode.name,
+    //         equivalencyValueChain,
+    //       },
+    //       null,
+    //       2,
+    //     ),
+    //   );
+    //   throw new Error('STOP - HIGH TRACEID');
+    // }
+
+    // Use this debugging to trace a specific path through the propagation
+    const debugLevel = 0; // 0 for minimal, 1 for executed paths, 2 for all paths info
+    // if ((!this.onlyEquivalencies && path === 'entity.sha') || traceId) {
+    //   traceId ||= 0;
+    //   traceId += 1;
+    //   if (traceId === 1) {
+    //     this.debugCount += 1;
+    //     if (this.debugCount > 5) throw new Error('STOP - HIGH DEBUG COUNT');
+    //     console.warn('START');
+    //   }
+
+    //   console.info(
+    //     'Debug Propagation: Adding to schema',
+    //     JSON.stringify(
+    //       {
+    //         // traceId,
+    //         path,
+    //         value,
+    //         scopeNodeName: scopeNode.name,
+    //         reason:
+    //           equivalencyValueChain[equivalencyValueChain.length - 1]?.reason,
+    //         // previous:
+    //         //   equivalencyValueChain[equivalencyValueChain.length - 1],
+    //         text: scopeNode.text,
+    //         // tree: scopeNode.tree,
+    //         // onlyEquivalencies: this.onlyEquivalencies,
+    //         // equivalencyValueChain,
+    //         // scopeNode
+    //         // instatiatedVeriables: scopeNode.instantiatedVariables,
+    //         // parentInstantiatedVariables: scopeNode.parentInstantiatedVariables,
+    //         // isolatedStructure: scopeNode.analysis.isolatedStructure,
+    //         // isolatedEquivalencies: scopeNode.analysis.isolatedEquivalentVariables,
+    //         // equivalencies: traceId === 1 ? scopeNode.equivalencies : 'skipped',
+    //         // functionCalls: scopeNode.functionCalls,
+    //         // externalFunctionCalls: this.externalFunctionCalls.filter(fc => fc.callScope.includes(scopeNode.name))
+    //       },
+    //       null,
+    //       2,
+    //     ),
+    //   );
+    //   // if (traceId > 1) traceId = undefined;
+    //   throw new Error('STOP ON ADD');
+    // }
+
+    const equivalenciesDatabaseEntry = this.getEquivalenciesDatabaseEntry(
+      scopeNode.name,
+      path,
+    );
+
+    this.addComplexSourcePathVariables(
+      equivalenciesDatabaseEntry,
+      scopeNode,
+      path,
+      equivalencyValueChain,
+      traceId,
+    );
+
+    const uniqueIdentifier = `${scopeNode.name}::${path}::${value}`;
+
+    if (this.globalVisited.has(uniqueIdentifier)) {
+      if (traceId) {
+        console.info(
+          'Debug propagation: already globally visited path',
+          JSON.stringify(
+            {
+              uniqueIdentifier,
+              // equivalencyValueChain,
+            },
+            null,
+            2,
+          ),
+        );
+      }
+
+      if (!this.onlyEquivalencies) {
+        this.addToEquivalencyDatabase(equivalencyValueChain, traceId);
+      }
+
+      return;
+    }
+
+    this.globalVisited.add(uniqueIdentifier);
+
+    this.captureComplexSourcePaths(
+      equivalenciesDatabaseEntry,
+      scopeNode,
+      path,
+      equivalencyValueChain,
+      traceId,
+    );
+
+    const pathParts = this.splitPath(path);
+
+    this.checkForArrayItemPath(pathParts, scopeNode, equivalencyValueChain);
+
+    let propagated = false;
+    for (let i = 0; i < pathParts.length; ++i) {
+      const subPathParts = pathParts.slice(0, i + 1);
+      const subPath = this.joinPathParts(subPathParts);
+
+      // Phase 2 optimization: Skip subpaths with no equivalencies since no managers run
+      if (!this.onlyEquivalencies) {
+        const hasEquivalencies = scopeNode.equivalencies[subPath]?.length > 0;
+        let hasFunctionEquivalencies = false;
+        if (subPathParts[subPathParts.length - 1].indexOf('(') > -1) {
+          const functionAmbivalentSubPathParts = [
+            ...subPathParts.slice(0, -1),
+            subPathParts[subPathParts.length - 1].split('(')[0],
+          ];
+          const functionAmbivalentSubPath = this.joinPathParts(
+            functionAmbivalentSubPathParts,
+          );
+          hasFunctionEquivalencies =
+            scopeNode.equivalencies[functionAmbivalentSubPath]?.length > 0;
+        }
+
+        if (!hasEquivalencies && !hasFunctionEquivalencies) {
+          // In phase 2, skip any subpath with no equivalencies since managers don't run
+          continue;
+        }
+      }
+
+      if (traceId && debugLevel > 1) {
+        console.info('Debug Propagation: subPath', {
+          traceId,
+          subPath,
+          path,
+          scopeNodeName: scopeNode.name,
+        });
+      }
+
+      this.followEquivalencies(
+        scopeNode,
+        path,
+        pathParts,
+        subPath,
+        subPathParts,
+        value,
+        equivalencyValueChain,
+        traceId,
+        debugLevel,
+      );
+
+      if (this.onlyEquivalencies) {
+        // Filter managers to only those interested in this subpath
+        const interestedManagers = this.equivalencyManagers.filter(
+          (manager) => {
+            if (manager.isInterestedInSubpath) {
+              return manager.isInterestedInSubpath(
+                subPathParts,
+                scopeNode,
+                this,
+              );
+            }
+            // If the manager doesn't implement the method, assume it's interested
+            return true;
+          },
+        );
+
+        for (const manager of interestedManagers) {
+          if (traceId && debugLevel > 1) {
+            console.info('Debug Propagation: manager equivalency check', {
+              traceId,
+              path,
+              subPath,
+              managerName: manager.toString(),
+              totalManagers: this.equivalencyManagers.length,
+              interestedManagers: interestedManagers.length,
+            });
+          }
+
+          const equivalencyPropagated = manager.addEquivalencies({
+            scopeDataStructure: this,
+            scopeNode,
+            path,
+            subPathParts,
+            value,
+            equivalencyValueChain,
+            traceId,
+            debugLevel,
+          });
+
+          if (equivalencyPropagated) {
+            if (traceId && debugLevel > 0) {
+              console.info('Debug Propagation: manager propagated', {
+                traceId,
+                path,
+                subPath,
+                scopeNodeName: scopeNode.name,
+                managerName: manager.toString(),
+              });
+            }
+
+            propagated = true;
+          }
+        }
+
+        if (traceId && debugLevel > 0) {
+          console.info('Debug Propagation: end of manager checks', {
+            traceId,
+            path,
+            subPath,
+            scopeNodeName: scopeNode.name,
+            propagated,
+          });
+        }
+      }
+    }
+
+    const writeToCurrentScopeSchema =
+      (!scopeNode.schema[path] || scopeNode.schema[path] === 'unknown') &&
+      (!scopeNode.instantiatedVariables ||
+        scopeNode.instantiatedVariables.includes(pathParts[0]) ||
+        pathParts[0].startsWith('signature[') ||
+        pathParts[0].startsWith('returnValue'));
+
+    // Safe early exit: if we've already set this exact schema value, skip processing
+    if (scopeNode.schema[path] === value && value !== 'unknown') {
+      return;
+    }
+
+    if (writeToCurrentScopeSchema) {
+      if (traceId && debugLevel > 0) {
+        console.info('Debug Propagation: currentScope executed', {
+          traceId,
+          path,
+          pathParts,
+          scopeNodeName: scopeNode.name,
+        });
+      }
+      scopeNode.schema[path] = value;
+    }
+
+    if (!this.onlyEquivalencies) {
+      this.addToEquivalencyDatabase(equivalencyValueChain, traceId);
+    }
+
+    if (traceId) {
+      console.info(
+        'Debug Propagation: exiting',
+        JSON.stringify(
+          {
+            traceId,
+            scopeNodeName: scopeNode.name,
+            path,
+            value,
+            // schemaValue: scopeNode.schema[path],
+            // propagated,
+            // scopeInfoText: scopeNode.text,
+            // equivalencyValueChain//: equivalencyValueChain.map(
+            //   (ev) => ev.currentPath.schemaPath,
+            // ),
+            // sourceEquivalencies: scopeNode.sourceEquivalencies[path] ?? [],
+            // usageEquivalencies: scopeNode.usageEquivalencies[path] ?? [],
+            // checkpoints,
+          },
+          null,
+          2,
+        ),
+      );
+    }
+  }
+
+  removeFromSchema(
+    path: string,
+    schema: Record<string, string> = {},
+    scopeName: string,
+  ) {
+    delete schema[path];
+  }
+
+  addEquivalency(
+    path: string,
+    equivalentPath: string,
+    equivalentScopeName: string,
+    scopeNode: ScopeNode,
+    equivalencyReason: string,
+    equivalencyValueChain?: EquivalencyValueChainItem[],
+    traceId?: number,
+  ) {
+    // Temporary debugging to track down unnecessary equivalencies
+    if (
+      ![
+        'original equivalency',
+        'implicit parent equivalency',
+        'explicit parent equivalency',
+        'transformed non-object function equivalency - original equivalency',
+        'equivalency to external function call',
+        'functionCall to function signature equivalency', // 1 failure
+        'explicit parent signature',
+        'useState setter call equivalency',
+        'non-object function argument function signature equivalency1',
+        'non-object function argument function signature equivalency2',
+        'returnValue to functionCallReturnValue equivalency', // 2 failures
+        '.map() function deconstruction', // 1 failure
+        'useMemo return value equivalent to first argument return value',
+        'useState value equivalency', // 1 failure
+        'Node .then() equivalency', // 1 failure
+        'Explicit array deconstruction equivalency value', // 1 failure
+        'forwardRef equivalency',
+        'forwardRef signature to child signature equivalency', // 1 failure
+        'captured function call return value equivalency', // 1 failure (in ScopeDataStructure.test.ts)
+        'original equivalency - rerouted via useCallback', // 1 failure
+        'non-object function argument function signature equivalency1 - rerouted via useCallback', // 1 failure
+        'non-object function argument function signature equivalency2 - rerouted via useCallback', // 1 failure
+        'implicit parent equivalency - rerouted via useCallback', // 1 failure
+        'Spread operator equivalency key update: implicit parent equivalency', // 1 failure
+        'Array.from() equivalency',
+      ].includes(equivalencyReason)
+    ) {
+      if (
+        [
+          'signature of functionCall',
+          'transformed non-object function equivalency - implicit parent equivalency',
+          'transformed non-object function equivalency - non-object function argument function signature equivalency1',
+          'transformed non-object function equivalency - non-object function argument function signature equivalency2',
+          'transformed non-object function equivalency - equivalency to external function call',
+          'Explicit array deconstruction equivalency key',
+          'transformed non-object function equivalency - useState setter call equivalency',
+          'transformed non-object function equivalency - implicit parent equivalency - rerouted via useCallback',
+          'transformed non-object function equivalency - Array.from() equivalency',
+          'Spread operator equivalency key update: Explicit array deconstruction equivalency value',
+        ].includes(equivalencyReason)
+      ) {
+        return;
+      } else {
+        console.info('Not tracked equivalency reason', { equivalencyReason });
+      }
+    }
+
+    if (!equivalentScopeName) {
+      console.warn('Debug Propagation: missing equivalent scope name', {
+        path,
+        equivalentPath,
+        equivalentScopeName,
+        scopeNodeName: scopeNode.name,
+      });
+      throw new Error('CodeYam Error: Missing equivalent scope name');
+    }
+
+    scopeNode.equivalencies[path] ||= [];
+
+    const existing = scopeNode.equivalencies[path];
+    if (
+      existing.find(
+        (v) =>
+          v.schemaPath === equivalentPath &&
+          v.scopeNodeName === equivalentScopeName,
+      )
+    ) {
+      return;
+    }
+
+    const id = ++this.lastEquivalencyId;
+    const equivalentValue: ScopeVariable = {
+      id,
+      scopeNodeName: equivalentScopeName,
+      schemaPath: equivalentPath,
+      equivalencyReason,
+    };
+    scopeNode.equivalencies[path].push(equivalentValue);
+
+    const equivalentScopeNode = this.getScopeOrFunctionCallInfo(
+      equivalentScopeName,
+    ) as ScopeNode;
+    if (equivalentScopeNode) {
+      this.removeFromSchema(
+        equivalentPath,
+        equivalentScopeNode.schema,
+        equivalentScopeNode.name,
+      );
+      this.addToSchema({
+        path: equivalentPath,
+        value: 'unknown',
+        scopeNode: equivalentScopeNode,
+        equivalencyValueChain: [
+          ...(equivalencyValueChain ?? []),
+          {
+            id: equivalentValue.id,
+            source: 'new equivalency',
+            reason: equivalencyReason,
+            previousPath: {
+              scopeNodeName: scopeNode.name,
+              schemaPath: path,
+              value: scopeNode.schema[path],
+            },
+          },
+        ],
+        traceId,
+      });
+    }
+  }
+
+  removeEquivalency(
+    path: string,
+    equivalency: ScopeVariable,
+    scopeNode: Pick<ScopeNode, 'equivalencies'>,
+  ) {
+    const equivalencies = scopeNode.equivalencies[path];
+    if (!equivalencies) return;
+
+    const index = equivalencies.findIndex(
+      (eq) =>
+        eq.scopeNodeName === equivalency.scopeNodeName &&
+        eq.schemaPath === equivalency.schemaPath,
+    );
+    if (index !== -1) {
+      equivalencies.splice(index, 1);
+    }
+
+    if (equivalencies.length === 0) {
+      delete scopeNode.equivalencies[path];
+    }
+  }
+
+  /**
+   * Adds a function call to either the internal scope nodes or external function calls list.
+   *
+   * A function call is considered "external" if:
+   * - It's not defined as a scope node in the codebase being analyzed
+   * - The function name is NOT in the calling scope's instantiatedVariables
+   * - The function name is NOT in the calling scope's parentInstantiatedVariables
+   *
+   * This means:
+   * - Imported functions (from external modules) are treated as external
+   * - Framework functions (useMemo, useState, etc.) are treated as external
+   * - Functions defined in parent scopes are treated as internal (not external)
+   *
+   * External function calls are tracked separately so we can infer their schemas
+   * from how they're used in the code, even without having their implementation.
+   */
+  addFunctionCall(
+    callingScopeNode: ScopeNode,
+    functionCallInfo: FunctionCallInfo,
+  ) {
+    functionCallInfo.name = cleanScopeNodeName(functionCallInfo.name);
+
+    const functionScope = this.scopeNodes[functionCallInfo.name];
+
+    if (functionScope) {
+      const existingFunctionCall = functionScope.functionCalls.find(
+        (fc) =>
+          fc.callSignature === functionCallInfo.callSignature &&
+          fc.callScope === functionCallInfo.callScope,
+      );
+      if (!existingFunctionCall) {
+        functionScope.functionCalls.push(functionCallInfo);
+      }
+    } else {
+      if (!functionCallInfo.schema) {
+        functionCallInfo.schema = {};
+      }
+      if (!functionCallInfo.equivalencies) {
+        functionCallInfo.equivalencies = {};
+      }
+
+      const existingFunctionCall = this.externalFunctionCalls.find(
+        (fc) => getFunctionCallRoot(functionCallInfo.callSignature) === fc.name,
+      );
+      if (existingFunctionCall) {
+        existingFunctionCall.schema = {
+          ...existingFunctionCall.schema,
+          ...functionCallInfo.schema,
+        };
+
+        existingFunctionCall.equivalencies = {
+          ...existingFunctionCall.equivalencies,
+          ...functionCallInfo.equivalencies,
+        };
+      } else {
+        const functionCallInfoNameParts = this.splitPath(functionCallInfo.name);
+        const isExternal =
+          !callingScopeNode.instantiatedVariables?.includes(
+            functionCallInfoNameParts[0],
+          ) &&
+          !callingScopeNode.parentInstantiatedVariables?.includes(
+            functionCallInfoNameParts[0],
+          );
+
+        if (isExternal) {
+          this.externalFunctionCalls.push(functionCallInfo);
+        }
+      }
+    }
+  }
+
+  propagateSourceAndUsageEquivalencies(
+    scopeNode: ScopeNode | FunctionCallInfo,
+    traceId?: number,
+  ) {
+    // if (traceId) {
+    //   traceId = 1;
+    //   console.info(
+    //     'Debug Propagate: entering propagateSourceAndUsageEquivalencies',
+    //     JSON.stringify(
+    //       {
+    //         traceId,
+    //         // a: this.scopeNodes['AnalysisLink____cyScope35']?.schema,
+    //         checkpoints,
+    //       },
+    //       null,
+    //       2,
+    //     ),
+    //   );
+    // }
+
+    const getRootOrExternalFunctionCallInfo = (name: string) => {
+      return name === this.scopeTree.name
+        ? this.getScopeNode()
+        : this.getExternalFunctionCallInfo(name);
+    };
+
+    const equateSchema = (
+      path: string,
+      scopeNode: ScopeNode | FunctionCallInfo,
+      equivalentPath: string,
+      equivalentScopeNode: ScopeNode | FunctionCallInfo,
+    ) => {
+      let safePath = path;
+      if (safePath.startsWith(`${scopeNode.name}F.`)) {
+        safePath = safePath.slice(scopeNode.name.length + 2);
+      }
+
+      const pathParts = this.splitPath(safePath);
+      const equivalentPathParts = this.splitPath(equivalentPath);
+
+      // Performance optimization: pre-filter schema paths to avoid unnecessary processing
+      const relevantSchemaPaths = Object.keys(scopeNode.schema).filter(
+        (schemaPath) => {
+          // Quick string check before expensive path splitting
+          return (
+            schemaPath.startsWith(safePath) ||
+            schemaPath === safePath ||
+            safePath.startsWith(schemaPath)
+          );
+        },
+      );
+
+      for (const schemaPath of relevantSchemaPaths) {
+        const schemaPathParts = this.splitPath(schemaPath);
+
+        if (!pathParts.every((p, i) => schemaPathParts[i] === p)) {
+          continue;
+        }
+
+        const remainingSchemaPathParts = schemaPathParts.slice(
+          pathParts.length,
+        );
+
+        let missingEquivalentPath = false;
+
+        // Performance optimization: pre-filter equivalent schema paths
+        const relevantEquivalentSchemaPaths = Object.keys(
+          equivalentScopeNode.schema,
+        ).filter((equivalentSchemaPath) => {
+          // Quick string check before expensive path splitting
+          return (
+            equivalentSchemaPath.startsWith(equivalentPath) ||
+            equivalentSchemaPath === equivalentPath ||
+            equivalentPath.startsWith(equivalentSchemaPath)
+          );
+        });
+
+        for (const equivalentSchemaPath of relevantEquivalentSchemaPaths) {
+          const equivalentSchemaPathParts =
+            this.splitPath(equivalentSchemaPath);
+
+          if (
+            !equivalentPathParts.every(
+              (p, i) => equivalentSchemaPathParts[i] === p,
+            )
+          ) {
+            continue;
+          }
+
+          const remainingEquivalentSchemaPathParts =
+            equivalentSchemaPathParts.slice(equivalentPathParts.length);
+
+          if (
+            remainingSchemaPathParts.length !==
+              remainingEquivalentSchemaPathParts.length ||
+            !remainingEquivalentSchemaPathParts.every(
+              (p, i) => p === remainingSchemaPathParts[i],
+            )
+          ) {
+            missingEquivalentPath = true;
+            continue;
+          }
+          missingEquivalentPath = false;
+
+          const value1 = scopeNode.schema[schemaPath];
+          const value2 = equivalentScopeNode.schema[equivalentSchemaPath];
+
+          let bestValue = value1 ?? value2 ?? 'unknown';
+          if (
+            value2 &&
+            ((bestValue === 'unknown' && value2 !== 'unknown') ||
+              (bestValue.includes('unknown') && !value2.includes('unknown')))
+          ) {
+            bestValue = value2;
+          }
+
+          scopeNode.schema[schemaPath] = bestValue;
+          equivalentScopeNode.schema[equivalentSchemaPath] = bestValue;
+
+          // if (traceId) {
+          //   console.info('Debug Propagate: Assign Best Value', {
+          //     traceId,
+          //     sourceScopeNodeName: scopeNode.name,
+          //     path,
+          //     schemaPath,
+          //     usageScopeNodeName: equivalentScopeNode.name,
+          //     equivalentPath,
+          //     equivalentSchemaPath,
+          //     remainingSchemaPathParts,
+          //     remainingEquivalentSchemaPathParts,
+          //     value1,
+          //     value2,
+          //     bestValue,
+          //   });
+          // }
+          break;
+        }
+
+        if (
+          missingEquivalentPath &&
+          (scopeNode.name.includes('____cyScope') ||
+            !('instantiatedVariables' in equivalentScopeNode))
+        ) {
+          // Only necessary for internal function scopes or external function scopes
+          const newEquivalentPath = this.joinPathParts([
+            equivalentPath,
+            ...remainingSchemaPathParts,
+          ]);
+
+          // if (traceId) {
+          //   console.info('Debug Propagate: missing equivalent path', {
+          //     traceId,
+          //     scopeNodeName: scopeNode.name,
+          //     path,
+          //     equivalentPath,
+          //     schemaPath,
+          //     remainingSchemaPathParts,
+          //     equivalentScopeNodeName: equivalentScopeNode.name,
+          //     // equivalentScopeNodeSchema: equivalentScopeNode.schema,
+          //     newEquivalentPath,
+          //   });
+          // }
+
+          equivalentScopeNode.schema[newEquivalentPath] =
+            scopeNode.schema[schemaPath];
+        }
+      }
+    };
+
+    const usageEquivalencies = this.getUsageEquivalencies(scopeNode.name);
+
+    // Performance optimization: cache scope node lookups
+    const scopeNodeCache = new Map<
+      string,
+      ScopeNode | FunctionCallInfo | null
+    >();
+
+    for (const path in usageEquivalencies) {
+      for (const usageEquivalency of usageEquivalencies[path]) {
+        let usageEquivalencyScopeNode = scopeNodeCache.get(
+          usageEquivalency.scopeNodeName,
+        );
+        if (usageEquivalencyScopeNode === undefined) {
+          usageEquivalencyScopeNode = getRootOrExternalFunctionCallInfo(
+            usageEquivalency.scopeNodeName,
+          );
+          scopeNodeCache.set(
+            usageEquivalency.scopeNodeName,
+            usageEquivalencyScopeNode,
+          );
+        }
+
+        if (!usageEquivalencyScopeNode) continue;
+
+        equateSchema(
+          path,
+          scopeNode,
+          usageEquivalency.schemaPath,
+          usageEquivalencyScopeNode,
+        );
+      }
+    }
+  }
+
+  splitPath(path: string): string[] {
+    if (this.pathPartsCache.has(path)) {
+      return structuredClone(this.pathPartsCache.get(path)!);
+    }
+    const pathParts = splitOutsideParenthesesAndArrays(path);
+    this.pathPartsCache.set(path, structuredClone(pathParts));
+    return pathParts;
+  }
+
+  joinPathParts(pathParts: string[]): string {
+    const cacheKey = pathParts.join('|');
+    if (this.pathJoinCache.has(cacheKey)) {
+      return this.pathJoinCache.get(cacheKey)!;
+    }
+    const result = joinParenthesesAndArrays(pathParts);
+    this.pathJoinCache.set(cacheKey, result);
+    return result;
+  }
+
+  // PRIVATE METHODS //
+
+  private uniqueId({
+    scopeNodeName,
+    schemaPath,
+    value,
+  }: {
+    scopeNodeName: string;
+    schemaPath: string;
+    value?: string;
+  }): string {
+    const parts = [scopeNodeName, schemaPath, value].filter(Boolean);
+    return parts.join('::');
+  }
+
+  private uniqueScopeVariables(scopeVariables: ScopeVariable[]) {
+    return this.uniqueScopeAndPaths(scopeVariables) as ScopeVariable[];
+  }
+
+  private uniqueScopeAndPaths(
+    scopeVariables: Pick<ScopeVariable, 'scopeNodeName' | 'schemaPath'>[],
+  ) {
+    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;
+    });
+  }
+
+  private isValidPath(path: string): boolean {
+    if (typeof path !== 'string') {
+      return false;
+    }
+
+    if (!path) {
+      return false;
+    }
+
+    if (path === 'true' || path === 'false') {
+      return false;
+    }
+
+    if (!isNaN(Number(path))) {
+      return false;
+    }
+
+    if (path.match(/^['"]/)) {
+      return false;
+    }
+
+    return this.splitPath(path).every((part) => {
+      if (
+        cleanOutBoundary(
+          cleanOutBoundary(cleanOutBoundary(part, '<', '>'), '[', ']'),
+        ).match(/\s/)
+      ) {
+        return false;
+      }
+      return true;
+    });
+  }
+
+  private addToTree(pathParts: string[]) {
+    let scopeTreeNode = { children: [this.scopeTree] };
+    for (const pathPart of pathParts) {
+      const existingChild = scopeTreeNode.children.find(
+        (child) => child.name === pathPart,
+      );
+      if (existingChild) {
+        scopeTreeNode = existingChild;
+      } else {
+        const childScopeTreeNode = {
+          name: pathPart,
+          children: [] as any[],
+        };
+        scopeTreeNode.children.push(childScopeTreeNode);
+        scopeTreeNode = childScopeTreeNode;
+      }
+    }
+  }
+
+  private setInstantiatedVariables(scopeNode: ScopeNode) {
+    let instantiatedVariables = scopeNode.analysis?.instantiatedVariables ?? [];
+
+    for (const [path, equivalentPath] of Object.entries(
+      scopeNode.analysis.isolatedEquivalentVariables ?? {},
+    )) {
+      if (typeof equivalentPath !== 'string') {
+        continue;
+      }
+
+      if (equivalentPath.startsWith('signature[')) {
+        const equivalentPathParts = this.splitPath(equivalentPath);
+        instantiatedVariables.push(equivalentPathParts[0]);
+        instantiatedVariables.push(path);
+      }
+
+      const duplicateInstantiated = instantiatedVariables.find(
+        (v) =>
+          path.split('::cyDuplicateKey')[0] === v.split('::cyDuplicateKey')[0],
+      );
+
+      if (duplicateInstantiated) {
+        instantiatedVariables.push(path);
+      }
+    }
+
+    instantiatedVariables = instantiatedVariables.filter(
+      (varName, index, self) => self.indexOf(varName) === index,
+    );
+
+    scopeNode.instantiatedVariables = instantiatedVariables;
+
+    if (!scopeNode.tree || scopeNode.tree.length === 0) {
+      return;
+    }
+
+    const parentScopeNode = this.getScopeOrFunctionCallInfo(
+      scopeNode.tree[scopeNode.tree.length - 1],
+    ) as ScopeNode;
+
+    if (!parentScopeNode) {
+      return;
+    }
+
+    const parentInstantiatedVariables = [
+      ...(parentScopeNode.parentInstantiatedVariables ?? []),
+      ...parentScopeNode.instantiatedVariables.filter(
+        (v) => !v.startsWith('signature[') && !v.startsWith('returnValue'),
+      ),
+    ].filter(
+      (varName, index, self) =>
+        !instantiatedVariables.includes(varName) &&
+        self.indexOf(varName) === index,
+    );
+
+    scopeNode.parentInstantiatedVariables = parentInstantiatedVariables;
+  }
+
+  private trackFunctionCalls(scopeNode: ScopeNode) {
+    this.captureFunctionCalls(scopeNode);
+    this.checkExternalFunctionCalls();
+  }
+
+  private determineEquivalenciesAndBuildSchema(scopeNode: ScopeNode) {
+    const { isolatedStructure, isolatedEquivalentVariables } =
+      scopeNode.analysis;
+
+    const allPaths = Array.from(
+      new Set([
+        ...Object.keys(isolatedStructure || {}),
+        ...Object.keys(isolatedEquivalentVariables || {}),
+        ...Object.values(isolatedEquivalentVariables || {}),
+      ]),
+    );
+
+    for (let path in isolatedEquivalentVariables) {
+      let equivalentValue = isolatedEquivalentVariables?.[path];
+
+      if (equivalentValue && this.isValidPath(equivalentValue)) {
+        path = cleanPath(path.replace(/::cyDuplicateKey\d+::/g, ''), allPaths);
+        equivalentValue = cleanPath(
+          equivalentValue.replace(/::cyDuplicateKey\d+::/g, ''),
+          allPaths,
+        );
+
+        this.addEquivalency(
+          path,
+          equivalentValue,
+          scopeNode.name,
+          scopeNode,
+          'original equivalency',
+        );
+      }
+    }
+
+    for (const key of Array.from(allPaths)) {
+      let value = isolatedStructure[key] ?? 'unknown';
+
+      if (['null', 'undefined'].includes(value)) {
+        value = 'unknown';
+      }
+
+      const startTime = new Date().getTime();
+      this.addToSchema({
+        path: cleanPath(key, allPaths),
+        value,
+        scopeNode,
+        equivalencyValueChain: [
+          {
+            id: -1,
+            source: 'Start: determineEquivalenciesAndBuildSchema',
+            reason: 'isolated structure',
+          },
+        ],
+      });
+
+      // const timeDiff = new Date().getTime() - startTime;
+      // if (timeDiff / 1000 > 1) {
+      //   console.info('SLOW', {
+      //     timeDiff,
+      //     root: this.scopeTree.name,
+      //     scopeNodeName: scopeNode.name,
+      //     schemaPath: key,
+      //     onlyEquivalencies: this.onlyEquivalencies,
+      //   });
+      // }
+    }
+
+    this.validateSchema(scopeNode, false, false);
+  }
+
+  private checkForArrayItemPath(
+    pathParts: string[],
+    scopeNode: ScopeNode,
+    equivalencyValueChain: EquivalencyValueChainItem[],
+  ) {
+    const arrayItemPath = joinParenthesesAndArrays([...pathParts, '[]']);
+    if (scopeNode.equivalencies[arrayItemPath]) {
+      const firstEquivalency = equivalencyValueChain[0].currentPath;
+      const newFirstEquivalencyPath = joinParenthesesAndArrays([
+        ...splitOutsideParenthesesAndArrays(firstEquivalency.schemaPath),
+        '[]',
+      ]);
+      this.addToSchema({
+        path: newFirstEquivalencyPath,
+        value: 'unknown',
+        scopeNode: this.scopeNodes[firstEquivalency.scopeNodeName],
+        equivalencyValueChain: [
+          {
+            id: -1,
+            source: 'Start: explicit array item',
+            reason: 'Adding explicit array item to schema',
+          },
+        ],
+      });
+    }
+  }
+
+  private followEquivalencies(
+    scopeNode: ScopeNode,
+    path: string,
+    pathParts: string[],
+    subPath: string,
+    subPathParts: string[],
+    value: string,
+    equivalencyValueChain: EquivalencyValueChainItem[],
+    traceId?: number,
+    debugLevel = 0,
+  ) {
+    followEquivalenciesCallCount++;
+    let propagated = false;
+    let equivalentValues = scopeNode.equivalencies[subPath] ?? [];
+    let functionAmbivalentSubPath = subPath;
+    let functionAmbivalentSubPathParts = subPathParts;
+
+    if (subPathParts[subPathParts.length - 1].indexOf('(') > -1) {
+      functionAmbivalentSubPathParts = [
+        ...subPathParts.slice(0, -1),
+        subPathParts[subPathParts.length - 1].split('(')[0],
+      ];
+      functionAmbivalentSubPath = this.joinPathParts(
+        functionAmbivalentSubPathParts,
+      );
+      equivalentValues = [
+        ...(equivalentValues ?? []),
+        ...(scopeNode.equivalencies[functionAmbivalentSubPath] ?? []),
+      ];
+    }
+
+    // Early exit optimization: if no equivalencies to follow, skip expensive processing
+    if (equivalentValues.length === 0) {
+      return false;
+    }
+
+    if (traceId && debugLevel > 1) {
+      console.info(
+        'Debug Propagation: equivalence',
+        JSON.stringify(
+          {
+            traceId,
+            propagated,
+            path,
+            subPath,
+            functionAmbivalentSubPath,
+            scopeNodeName: scopeNode.name,
+            equivalentValuesLength: equivalentValues.length,
+            equivalentValues,
+            // scopeInfoEquivalencies: scopeNode.equivalencies,
+            // equivalencyValueChain,
+          },
+          null,
+          2,
+        ),
+      );
+    }
+
+    const uniqueEquivalentValues = this.uniqueScopeVariables(equivalentValues);
+
+    for (let index = 0; index < uniqueEquivalentValues.length; ++index) {
+      const equivalentValue = uniqueEquivalentValues[index];
+
+      if (
+        equivalentValue.id !== -1 &&
+        equivalencyValueChain.some((ev) => ev.id === equivalentValue.id)
+      ) {
+        if (traceId) {
+          console.info(
+            'Debug Propagation: skipping circular equivalence',
+            JSON.stringify(
+              {
+                traceId,
+                path,
+                subPath,
+                functionAmbivalentSubPath,
+                scopeNodeName: scopeNode.name,
+                equivalentValue,
+                equivalencyValueChain,
+              },
+              null,
+              2,
+            ),
+          );
+        }
+        continue;
+      }
+
+      if (
+        (subPath.startsWith('signature[') ||
+          (subPathParts[0].startsWith(scopeNode.name) &&
+            subPathParts[1]?.startsWith('signature['))) &&
+        equivalentValue.scopeNodeName === scopeNode.name
+      ) {
+        continue;
+      }
+
+      let { schemaPath } = equivalentValue;
+      const schemaPathParts = this.splitPath(schemaPath);
+
+      const equivalentScopeNode = this.getScopeOrFunctionCallInfo(
+        equivalentValue.scopeNodeName,
+      ) as ScopeNode;
+
+      const relevantSubPathParts = subPathParts.slice(
+        0,
+        functionAmbivalentSubPathParts.length,
+      );
+
+      const lastRelevantSubPathPart =
+        relevantSubPathParts[relevantSubPathParts.length - 1];
+      if (
+        lastRelevantSubPathPart.endsWith(')') &&
+        schemaPathParts[schemaPathParts.length - 1] ===
+          lastRelevantSubPathPart.split('(')[0]
+      ) {
+        schemaPathParts[schemaPathParts.length - 1] = lastRelevantSubPathPart;
+        schemaPath = this.joinPathParts(schemaPathParts);
+      }
+
+      const remainingPathParts = pathParts.slice(relevantSubPathParts.length);
+      const remainingPath = this.joinPathParts(remainingPathParts);
+
+      if (
+        relevantSubPathParts.every((part, i) => part === schemaPathParts[i]) &&
+        equivalentValue.scopeNodeName === scopeNode.name
+      ) {
+        continue;
+      }
+
+      const newEquivalentPath = this.joinPathParts([schemaPath, remainingPath]);
+
+      if (!equivalentScopeNode) {
+        if (traceId) {
+          console.info('Debug Propagation: missing equivalent scope info', {
+            traceId,
+            path,
+            subPath,
+            functionAmbivalentSubPath,
+            scopeNodeName: scopeNode.name,
+            equivalentValue,
+            scopeInfos: Object.keys(this.scopeNodes),
+            efcs: this.externalFunctionCalls.map((efc) => efc.name),
+          });
+        }
+        continue;
+      }
+
+      if (
+        scopeNode.name !== equivalentValue.scopeNodeName ||
+        path !== newEquivalentPath
+      ) {
+        if (traceId && debugLevel > 0) {
+          console.info(
+            'Debug Propagation: equivalence executed',
+            JSON.stringify(
+              {
+                traceId,
+                path,
+                subPath,
+                functionAmbivalentSubPath,
+                schemaPath,
+                remainingPath,
+                scopeNodeName: scopeNode.name,
+                equivalentValue,
+                newEquivalentPath,
+                equivalentValuesCount: uniqueEquivalentValues.length,
+                equivalentValuesIndex: index,
+                // equivalentValues: uniqueEquivalentValues,
+                // equivalencies:  scopeNode.equivalencies,
+              },
+              null,
+              2,
+            ),
+          );
+        }
+
+        const localEquivalencyValueChain = structuredClone(
+          equivalencyValueChain,
+        );
+        localEquivalencyValueChain.push({
+          id: equivalentValue.id,
+          source: 'equivalence',
+          previousPath: {
+            scopeNodeName: scopeNode.name,
+            schemaPath: path,
+            value,
+          },
+          currentPath: {
+            scopeNodeName: equivalentScopeNode.name,
+            schemaPath: newEquivalentPath,
+            value,
+          },
+          reason: equivalentValue.equivalencyReason,
+          traceId,
+        });
+
+        // writeEquivalencyToFile(
+        //   scopeNode.name,
+        //   subPath,
+        //   equivalentValue.scopeNodeName,
+        //   equivalentValue.schemaPath,
+        //   newEquivalentPath,
+        //   equivalentValue.equivalencyReason,
+        // )
+
+        propagated = true;
+        this.addToSchema({
+          path: newEquivalentPath,
+          value,
+          scopeNode: equivalentScopeNode,
+          equivalencyValueChain: localEquivalencyValueChain,
+          traceId,
+        });
+      }
+    }
+
+    return propagated;
+  }
+
+  private addComplexSourcePathVariables(
+    equivalenciesDatabaseEntry: EquivalencyDatabaseEntry,
+    scopeNode: ScopeNode,
+    path: string,
+    equivalencyValueChain: EquivalencyValueChainItem[],
+    traceId?: number,
+  ) {
+    if (equivalenciesDatabaseEntry?.complexSourceEquivalencies?.size > 0) {
+      this.addToEquivalencyDatabase(equivalencyValueChain, traceId);
+
+      for (const remainingPath of equivalenciesDatabaseEntry.complexSourceEquivalencies) {
+        for (const usageEquivalency of equivalenciesDatabaseEntry.usages) {
+          const usageEquivalentPath = usageEquivalency.schemaPath;
+
+          if (usageEquivalentPath.includes(remainingPath)) return;
+
+          const newUsageEquivalentPath = this.joinPathParts([
+            usageEquivalentPath,
+            remainingPath,
+          ]);
+
+          if (
+            usageEquivalency.scopeNodeName === scopeNode.name &&
+            newUsageEquivalentPath === path
+          ) {
+            return;
+          }
+
+          const usageScopeNode = this.getScopeOrFunctionCallInfo(
+            usageEquivalency.scopeNodeName,
+          ) as ScopeNode;
+
+          this.addToSchema({
+            path: newUsageEquivalentPath,
+            value: 'unknown',
+            scopeNode: usageScopeNode,
+            equivalencyValueChain: [
+              {
+                id: -1,
+                source: 'complex usage equivalency 1',
+                reason: `complex usage equivalency 1`,
+              },
+            ],
+            traceId,
+          });
+        }
+      }
+    }
+  }
+
+  private captureComplexSourcePaths(
+    equivalenciesDatabaseEntry: EquivalencyDatabaseEntry,
+    scopeNode: ScopeNode,
+    path: string,
+    equivalencyValueChain: EquivalencyValueChainItem[],
+    traceId?: number,
+  ) {
+    if (
+      this.onlyEquivalencies ||
+      !equivalenciesDatabaseEntry ||
+      path !== 'returnValue'
+    ) {
+      return;
+    }
+
+    this.addToEquivalencyDatabase(equivalencyValueChain, traceId);
+
+    for (const equivalentPath in scopeNode.equivalencies) {
+      if (
+        equivalentPath !== 'returnValue' &&
+        equivalentPath.startsWith('returnValue')
+      ) {
+        const remainingParts = this.splitPath(equivalentPath).slice(1);
+
+        equivalenciesDatabaseEntry.complexSourceEquivalencies.add(
+          this.joinPathParts(remainingParts),
+        );
+
+        const skip: string[] = [];
+        for (const usageEquivalency of equivalenciesDatabaseEntry.usages) {
+          const usageEquivalentPath = usageEquivalency.schemaPath;
+          if (skip.includes(usageEquivalentPath)) continue;
+          const newUsageEquivalentPath = this.joinPathParts([
+            usageEquivalentPath,
+            ...remainingParts,
+          ]);
+
+          if (
+            equivalenciesDatabaseEntry.usages.find(
+              (u) => u.schemaPath === newUsageEquivalentPath,
+            )
+          ) {
+            skip.push(newUsageEquivalentPath);
+            continue;
+          }
+
+          const usageScopeNode = this.getScopeOrFunctionCallInfo(
+            usageEquivalency.scopeNodeName,
+          ) as ScopeNode;
+
+          // This is put in place to avoid propagating array functions like 'filter' through complex equivalencies
+          // but may cause problems if the funtion call is not on a known object (e.g. string or array)
+          if (
+            newUsageEquivalentPath.endsWith(')') ||
+            newUsageEquivalentPath.endsWith('functionCallReturnValue')
+          ) {
+            return;
+          }
+
+          this.addToSchema({
+            path: newUsageEquivalentPath,
+            value: 'unknown',
+            scopeNode: usageScopeNode,
+            equivalencyValueChain: [
+              {
+                id: -1,
+                source: 'complex usage equivalency 2',
+                reason: `complex usage equivalency 2`,
+              },
+            ],
+            traceId,
+          });
+        }
+      }
+    }
+  }
+
+  private addToEquivalencyDatabase(
+    equivalencyValueChain?: EquivalencyValueChainItem[],
+    traceId?: number,
+  ) {
+    if (equivalencyValueChain.length === 0) return;
+
+    // TODO: Make this more robust (needs to ensure no other non-array functions exist on the object)
+    const cleanEquivalencyValueChain = equivalencyValueChain.map((ev) => ({
+      ...ev,
+      currentPath: {
+        scopeNodeName: ev.currentPath.scopeNodeName,
+        schemaPath: cleanPathOfNonTransformingFunctions(
+          ev.currentPath.schemaPath,
+        ),
+      },
+      previousPath: ev.previousPath
+        ? {
+            scopeNodeName: ev.previousPath.scopeNodeName,
+            schemaPath: cleanPathOfNonTransformingFunctions(
+              ev.previousPath.schemaPath,
+            ),
+          }
+        : undefined,
+    }));
+
+    // Use inverted index for O(1) lookup instead of O(n) filter
+    const matchingEntriesSet = new Set<EquivalencyDatabaseEntry>();
+    for (const ev of cleanEquivalencyValueChain) {
+      const pathId = this.uniqueId(ev.currentPath);
+      const existingEntry = this.intermediatesOrderIndex.get(pathId);
+      if (existingEntry) {
+        matchingEntriesSet.add(existingEntry);
+      }
+    }
+    // Sort by id to maintain deterministic merge order (lowest id entry becomes survivor)
+    const databaseEntries = Array.from(matchingEntriesSet).sort(
+      (a, b) => a.id - b.id,
+    );
+
+    let databaseEntry = this.mergeEquivalencyDatabaseEntries(databaseEntries);
+
+    if (!databaseEntry) {
+      databaseEntry = {
+        id: ++this.lastEquivalencyDatabaseId,
+        sourceCandidates: [],
+        usages: [],
+        intermediatesOrder: {},
+        complexSourceEquivalencies: new Set<string>(),
+      };
+      this.equivalencyDatabase.push(databaseEntry);
+      this.equivalencyDatabaseCache.clear(); // Clear cache when database is modified
+    }
+
+    for (let i = 0; i < cleanEquivalencyValueChain.length; ++i) {
+      const pathInfo = cleanEquivalencyValueChain[i].currentPath;
+
+      const schemaPathParts = this.splitPath(pathInfo.schemaPath);
+      const isSignaturePath =
+        schemaPathParts.findIndex((p) => p.startsWith('signature[')) > 0;
+      if (
+        schemaPathParts[0].startsWith('returnValue') ||
+        isSignaturePath
+        // (isSignaturePath &&
+        //   pathInfo.schemaPath.startsWith(pathInfo.scopeNodeName))
+      ) {
+        databaseEntry.usages.push(pathInfo);
+      }
+
+      const pathId = this.uniqueId(pathInfo);
+      let intermediateIndex = cleanEquivalencyValueChain.length - i - 1;
+      const existingIntermediateIndex =
+        databaseEntry.intermediatesOrder[pathId];
+      if (existingIntermediateIndex !== undefined) {
+        intermediateIndex = Math.max(
+          intermediateIndex,
+          existingIntermediateIndex,
+        );
+      }
+      databaseEntry.intermediatesOrder[pathId] = intermediateIndex;
+      // Update inverted index
+      this.intermediatesOrderIndex.set(pathId, databaseEntry);
+
+      if (intermediateIndex === 0) {
+        const isValidSourceCandidate =
+          pathInfo.schemaPath.startsWith('signature[') ||
+          pathInfo.schemaPath.includes('functionCallReturnValue');
+        if (isValidSourceCandidate) {
+          databaseEntry.sourceCandidates.push(pathInfo);
+        }
+      } else {
+        const existingSourceCandidateIndex =
+          databaseEntry.sourceCandidates.findIndex(
+            (sc) =>
+              sc.scopeNodeName === pathInfo.scopeNodeName &&
+              sc.schemaPath === pathInfo.schemaPath,
+          );
+        if (existingSourceCandidateIndex > -1) {
+          databaseEntry.sourceCandidates.splice(
+            existingSourceCandidateIndex,
+            1,
+          );
+        }
+      }
+    }
+    databaseEntry.sourceCandidates = this.uniqueScopeAndPaths(
+      databaseEntry.sourceCandidates,
+    );
+    databaseEntry.usages = this.uniqueScopeAndPaths(databaseEntry.usages);
+  }
+
+  private mergeEquivalencyDatabaseEntries(
+    databaseEntries: EquivalencyDatabaseEntry[],
+  ) {
+    if (databaseEntries.length < 2) return databaseEntries[0];
+
+    const mergedDatabaseEntry = databaseEntries[0];
+    for (let i = 1; i < databaseEntries.length; ++i) {
+      const entryToMerge = databaseEntries[i];
+
+      mergedDatabaseEntry.sourceCandidates.push(
+        ...entryToMerge.sourceCandidates,
+      );
+      mergedDatabaseEntry.sourceCandidates = this.uniqueScopeAndPaths(
+        mergedDatabaseEntry.sourceCandidates,
+      );
+
+      mergedDatabaseEntry.usages.push(...entryToMerge.usages);
+      mergedDatabaseEntry.usages = this.uniqueScopeAndPaths(
+        mergedDatabaseEntry.usages,
+      );
+
+      for (const pathId in entryToMerge.intermediatesOrder) {
+        const intermediateIndex = entryToMerge.intermediatesOrder[pathId];
+        const existingIntermediateIndex =
+          mergedDatabaseEntry.intermediatesOrder[pathId];
+        mergedDatabaseEntry.intermediatesOrder[pathId] = Math.max(
+          intermediateIndex ?? -1,
+          existingIntermediateIndex ?? -1,
+        );
+        // Update inverted index to point to the surviving entry
+        this.intermediatesOrderIndex.set(pathId, mergedDatabaseEntry);
+        if (
+          (intermediateIndex === 0 || existingIntermediateIndex === 0) &&
+          mergedDatabaseEntry.intermediatesOrder[pathId] > 0
+        ) {
+          mergedDatabaseEntry.sourceCandidates =
+            mergedDatabaseEntry.sourceCandidates.filter(
+              (sc) => pathId !== this.uniqueId(sc),
+            );
+        }
+      }
+
+      this.equivalencyDatabase = this.equivalencyDatabase.filter(
+        (de) => de.id !== entryToMerge.id,
+      );
+      this.equivalencyDatabaseCache.clear(); // Clear cache when database is modified
+    }
+    return mergedDatabaseEntry;
+  }
+
+  private checkExternalFunctionCalls() {
+    for (let i = 0; i < this.externalFunctionCalls.length; ++i) {
+      const externalFunctionCallInfo = this.externalFunctionCalls[i];
+      const functionScopeName = Object.keys(this.scopeNodes).find(
+        (scopeNodeName) =>
+          externalFunctionCallInfo.name ===
+          scopeNodeName.replace(/____cyScope\d+[A-Z]*/, ''),
+      );
+
+      if (!functionScopeName) continue;
+      const functionScope = this.scopeNodes[functionScopeName];
+
+      if (functionScope) {
+        functionScope.functionCalls.push(externalFunctionCallInfo);
+        this.externalFunctionCalls.splice(i, 1);
+
+        for (const equivalentPath in externalFunctionCallInfo.equivalencies) {
+          let localEquivalentPath = equivalentPath;
+          if (
+            localEquivalentPath.startsWith(
+              externalFunctionCallInfo.callSignature,
+            )
+          ) {
+            localEquivalentPath = this.joinPathParts(
+              this.splitPath(localEquivalentPath).slice(1),
+            );
+          }
+
+          functionScope.equivalencies[localEquivalentPath] =
+            this.uniqueScopeVariables([
+              ...(functionScope.equivalencies[localEquivalentPath] ?? []),
+              ...externalFunctionCallInfo.equivalencies[equivalentPath],
+            ]);
+        }
+
+        for (const functionCall of functionScope.functionCalls) {
+          const callingScopeNode = this.scopeNodes[functionCall.callScope];
+          if (!callingScopeNode) continue;
+
+          for (const [equivalentPath, equivalentValues] of Object.entries(
+            callingScopeNode.equivalencies,
+          )) {
+            if (equivalentPath.startsWith(functionCall.callSignature)) {
+              for (const equivalentValue of equivalentValues) {
+                if (equivalentValue.scopeNodeName === functionScope.name) {
+                  this.removeEquivalency(
+                    equivalentPath,
+                    equivalentValue,
+                    callingScopeNode,
+                  );
+                }
+              }
+            }
+
+            for (const equivalentValue of equivalentValues) {
+              const returnValueSchemaPath = this.joinPathParts([
+                functionCall.callSignature,
+                'functionCallReturnValue',
+              ]);
+              if (
+                equivalentValue.schemaPath === returnValueSchemaPath &&
+                equivalentValue.scopeNodeName === callingScopeNode.name
+              ) {
+                this.addEquivalency(
+                  returnValueSchemaPath,
+                  'returnValue',
+                  functionScope.name,
+                  callingScopeNode,
+                  'captured function call return value equivalency',
+                );
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  private captureFunctionCalls(scopeNode: ScopeNode) {
+    for (const key in scopeNode.equivalencies) {
+      const keyParts = this.splitPath(key);
+      if (keyParts.length > 1) {
+        const lastPart = keyParts.pop();
+        if (lastPart.startsWith('signature[')) {
+          const functionCall = keyParts[keyParts.length - 1];
+          const argumentsIndex = functionCall.indexOf('(');
+          const functionName = this.joinPathParts([
+            ...keyParts.slice(0, -1),
+            functionCall.slice(
+              0,
+              argumentsIndex === -1 ? undefined : argumentsIndex,
+            ),
+          ]);
+          const callSignature = this.joinPathParts(keyParts);
+
+          const functionCallInfo = {
+            name: functionName,
+            callSignature,
+            callScope: scopeNode.name,
+          };
+
+          this.addFunctionCall(scopeNode, functionCallInfo);
+        }
+      }
+
+      for (const equivalentValues of scopeNode.equivalencies[key]) {
+        const equivalentValueParts = this.splitPath(
+          equivalentValues.schemaPath,
+        );
+        if (equivalentValueParts.length > 1) {
+          const lastPart = equivalentValueParts.pop();
+          if (lastPart.startsWith('functionCallReturnValue')) {
+            const functionCall =
+              equivalentValueParts[equivalentValueParts.length - 1];
+            const argumentsIndex = functionCall.indexOf('(');
+            const functionName = this.joinPathParts([
+              ...equivalentValueParts.slice(0, -1),
+              functionCall.slice(
+                0,
+                argumentsIndex === -1 ? undefined : argumentsIndex,
+              ),
+            ]);
+            const callSignature = this.joinPathParts(equivalentValueParts);
+
+            const functionCallInfo = {
+              name: functionName,
+              callSignature,
+              callScope: scopeNode.name,
+            };
+
+            this.addFunctionCall(scopeNode, functionCallInfo);
+          }
+        }
+      }
+    }
+  }
+
+  private validateSchema(
+    scopeNode: ScopeNode,
+    final: boolean,
+    fillInUnknowns: boolean,
+  ) {
+    for (const key in scopeNode.schema) {
+      if (!scopeNode.schema[key] || !this.isValidPath(key)) {
+        delete scopeNode.schema[key];
+      }
+    }
+
+    fillInSchemaGapsAndUnknowns(scopeNode, fillInUnknowns);
+
+    if (final) {
+      for (const manager of this.equivalencyManagers) {
+        manager.finalize(scopeNode, this);
+      }
+    }
+
+    if (final) {
+      fillInSchemaGapsAndUnknowns(scopeNode, fillInUnknowns);
+      ensureSchemaConsistency(scopeNode.schema);
+    }
+  }
+
+  private filterAndConvertSchema({
+    filterPath,
+    newPath,
+    schema,
+  }: {
+    filterPath: string;
+    newPath?: string;
+    schema: Record<string, string>;
+  }): Record<string, string> {
+    const filterPathParts = this.splitPath(filterPath);
+    return Object.keys(schema).reduce(
+      (acc, key) => {
+        const keyParts = this.splitPath(key);
+        if (!filterPathParts.every((part, index) => keyParts[index] === part)) {
+          return acc;
+        }
+        const newKey = this.joinPathParts([
+          newPath ?? filterPath,
+          ...keyParts.slice(filterPathParts.length),
+        ]);
+        acc[newKey] = schema[key];
+        return acc;
+      },
+      {} as Record<string, string>,
+    );
+  }
+
+  private resolvePathIntoSchema({
+    path,
+    scopeNode,
+    visited = {},
+  }: {
+    path: string;
+    scopeNode: ScopeNode;
+    visited?: Record<string, Set<string>>;
+  }) {
+    if (visited[scopeNode.name]?.has(path)) {
+      return;
+    }
+    visited[scopeNode.name] ||= new Set([]);
+    visited[scopeNode.name].add(path);
+
+    const pathParts = this.splitPath(path);
+    const resolvedSchema: ScopeNode['schema'] = {};
+    if (path.startsWith('signature[')) {
+      // for (const functionCall of scopeNode.functionCalls) {
+      //   console.warn(
+      //     'functionCall',
+      //     JSON.stringify(
+      //       { path, scopeNodeName: scopeNode.name, functionCall },
+      //       null,
+      //       2,
+      //     ),
+      //   );
+      // }
+    } else if (scopeNode.equivalencies[path]) {
+      for (const equivalentValue of scopeNode.equivalencies[path]) {
+        const equivalentScopeNode =
+          this.scopeNodes[equivalentValue.scopeNodeName];
+        if (equivalentScopeNode) {
+          const equivalentValueSchemaPathParts = this.splitPath(
+            equivalentValue.schemaPath,
+          );
+
+          const subSchema = this.resolvePathIntoSchema({
+            path: equivalentValue.schemaPath,
+            scopeNode: equivalentScopeNode,
+            visited,
+          });
+
+          if (!subSchema) {
+            // console.warn('CodeYam Warn: No SubSchema', {
+            //   path,
+            //   equivalentValue,
+            //   equivalentScopeNodeName: equivalentScopeNode.name,
+            // });
+            continue;
+          }
+
+          for (const [key, value] of Object.entries(subSchema)) {
+            const newKey = this.joinPathParts([
+              path,
+              ...this.splitPath(key).slice(
+                equivalentValueSchemaPathParts.length,
+              ),
+            ]);
+            resolvedSchema[newKey] = value;
+          }
+        }
+      }
+    }
+
+    for (const key of [
+      ...Object.keys(scopeNode.schema),
+      ...Object.keys(scopeNode.equivalencies),
+    ]) {
+      if (key === path) continue;
+
+      const keyParts = this.splitPath(key);
+      if (pathParts.every((part, index) => part === keyParts[index])) {
+        const subSchema = this.resolvePathIntoSchema({
+          path: key,
+          scopeNode,
+          visited,
+        });
+        if (!subSchema) continue;
+
+        for (const resolvedKey in subSchema) {
+          if (
+            !resolvedSchema[resolvedKey] ||
+            subSchema[resolvedKey] === 'unknown'
+          ) {
+            resolvedSchema[resolvedKey] = subSchema[resolvedKey];
+          }
+        }
+      }
+    }
+
+    if (!resolvedSchema[path] || resolvedSchema[path] === 'unknown') {
+      resolvedSchema[path] = scopeNode.schema[path] || 'unknown';
+    }
+
+    return resolvedSchema;
+  }
+
+  private functionOrScopeName(path: string) {
+    return path.split('<')[0].split('(')[0];
+  }
+
+  private createTempScopeNode(
+    name: string,
+    schema: ScopeNode['schema'] = {},
+    equivalencies: ScopeNode['equivalencies'] = {},
+  ): ScopeNode {
+    const tempScopeNode = {
+      name: name,
+      path: [],
+      analysis: {
+        instantiatedVariables: [],
+      },
+      schema,
+      equivalencies,
+    } as unknown as ScopeNode;
+
+    return tempScopeNode;
+  }
+
+  // GETTERS //
+
+  getScopeOrFunctionCallInfo(
+    scopeName?: string,
+  ): ScopeNode | FunctionCallInfo | undefined {
+    const scopeNode = this.getScopeNode(scopeName);
+    if (scopeNode) {
+      return scopeNode;
+    }
+
+    return this.getExternalFunctionCallInfo(scopeName);
+  }
+
+  getScopeNode(scopeName?: string): ScopeNode | undefined {
+    const scopeNode = this.scopeNodes[scopeName ?? this.scopeTree.name];
+    if (scopeNode) return scopeNode;
+
+    for (const scopeNodeName in this.scopeNodes) {
+      if (scopeNodeName.startsWith(`${scopeName}____cyScope`)) {
+        return this.scopeNodes[scopeNodeName];
+      }
+    }
+  }
+
+  getExternalFunctionCallInfo(
+    functionName: string,
+  ): FunctionCallInfo | undefined {
+    return this.externalFunctionCalls.find(
+      (efc) =>
+        efc.name === getFunctionCallRoot(functionName) ||
+        efc.name.split('<')[0] === getFunctionCallRoot(functionName),
+    );
+  }
+
+  getScopeAnalysis(scopeName?: string): ScopeAnalysis | undefined {
+    return this.scopeNodes[scopeName ?? this.scopeTree.name].analysis;
+  }
+
+  getAnalysisTree(): ScopeTreeNode {
+    return this.scopeTree;
+  }
+
+  getSchema({
+    scopeName,
+    fillInUnknowns,
+  }: {
+    scopeName?: string;
+    fillInUnknowns?: boolean;
+  }): any {
+    const scopeNode = this.scopeNodes[scopeName ?? this.scopeTree.name];
+
+    if (!scopeNode) {
+      const externalFunctionCallSchema = this.externalFunctionCalls.find(
+        (call) => call.name === getFunctionCallRoot(scopeName),
+      )?.schema;
+
+      if (!externalFunctionCallSchema) return;
+
+      return Object.keys(externalFunctionCallSchema).reduce(
+        (acc, key) => {
+          const keyParts = this.splitPath(key);
+          acc[this.joinPathParts(keyParts.slice(1))] =
+            externalFunctionCallSchema[key];
+          return acc;
+        },
+        {} as Record<string, string>,
+      );
+    }
+
+    this.validateSchema(scopeNode, true, fillInUnknowns);
+
+    const { schema } = scopeNode;
+    return schema;
+  }
+
+  getEquivalencies(scopeName?: string) {
+    const scopeNode = this.getScopeOrFunctionCallInfo(scopeName);
+    return scopeNode?.equivalencies;
+  }
+
+  getEquivalenciesDatabaseEntry(scopeNodeName: string, schemaPath: string) {
+    const cacheKey = `${scopeNodeName}::${schemaPath}`;
+
+    if (this.equivalencyDatabaseCache.has(cacheKey)) {
+      return this.equivalencyDatabaseCache.get(cacheKey);
+    }
+
+    const result = this.equivalencyDatabase.find(
+      (entry) => entry.intermediatesOrder[cacheKey] !== undefined,
+    );
+
+    this.equivalencyDatabaseCache.set(cacheKey, result);
+    return result;
+  }
+
+  getSourceEquivalencies(functionName?: string) {
+    const scopeNode = this.getScopeOrFunctionCallInfo(functionName);
+
+    if (!scopeNode) {
+      return {};
+    }
+
+    const entries = this.equivalencyDatabase.filter((entry) =>
+      entry.usages.some((usage) => usage.scopeNodeName === scopeNode.name),
+    );
+    return entries.reduce(
+      (acc, entry) => {
+        if (entry.sourceCandidates.length === 0) return acc;
+        const usages = entry.usages.filter(
+          (u) => u.scopeNodeName === scopeNode.name,
+        );
+        for (const usage of usages) {
+          acc[usage.schemaPath] ||= [];
+          acc[usage.schemaPath].push(...entry.sourceCandidates);
+        }
+        return acc;
+      },
+      {} as Record<
+        string,
+        Pick<ScopeVariable, 'scopeNodeName' | 'schemaPath'>[]
+      >,
+    );
+  }
+
+  getUsageEquivalencies(functionName?: string) {
+    const scopeNode = this.getScopeOrFunctionCallInfo(functionName);
+
+    if (!scopeNode) {
+      return {};
+    }
+
+    const entries = this.equivalencyDatabase.filter((entry) =>
+      entry.sourceCandidates.some(
+        (candidate) => candidate.scopeNodeName === scopeNode.name,
+      ),
+    );
+    return entries.reduce(
+      (acc, entry) => {
+        if (entry.usages.length === 0) return acc;
+        const sourceCandidates = entry.sourceCandidates.filter(
+          (u) => u.scopeNodeName === scopeNode.name,
+        );
+        for (const sourceCandidate of sourceCandidates) {
+          acc[sourceCandidate.schemaPath] ||= [];
+          acc[sourceCandidate.schemaPath].push(...entry.usages);
+        }
+        return acc;
+      },
+      {} as Record<
+        string,
+        Pick<ScopeVariable, 'scopeNodeName' | 'schemaPath'>[]
+      >,
+    );
+  }
+
+  getFunctionSignature({
+    functionName,
+    fillInUnknowns = false,
+  }: {
+    functionName?: string;
+    fillInUnknowns?: boolean;
+  }) {
+    const schema = this.getSchema({
+      scopeName: functionName,
+    });
+
+    if (!schema) return;
+
+    const signatureInSchema = Object.keys(schema)
+      .filter((key) => key.startsWith('signature['))
+      .reduce(
+        (acc, key) => {
+          acc[key] = schema[key];
+          return acc;
+        },
+        {} as Record<string, string>,
+      );
+
+    const equivalencies = this.getEquivalencies(functionName);
+    for (const equivalenceKey in equivalencies ?? {}) {
+      for (const equivalenceValue of equivalencies[equivalenceKey]) {
+        const schemaPath = equivalenceValue.schemaPath;
+        if (
+          schemaPath.startsWith('signature[') &&
+          equivalenceValue.scopeNodeName === functionName &&
+          !signatureInSchema[schemaPath]
+        ) {
+          signatureInSchema[schemaPath] = 'unknown';
+        }
+      }
+    }
+
+    const tempScopeNode = this.createTempScopeNode(
+      functionName ?? this.scopeTree.name,
+      signatureInSchema,
+      equivalencies,
+    );
+
+    this.validateSchema(tempScopeNode, true, fillInUnknowns);
+
+    return tempScopeNode.schema;
+  }
+
+  getReturnValue({
+    functionName,
+    fillInUnknowns,
+  }: {
+    functionName?: string;
+    fillInUnknowns?: boolean;
+  }) {
+    const scopeName = functionName ?? this.scopeTree.name;
+    const scopeNode = this.scopeNodes[scopeName];
+
+    let schema: ScopeNode['schema'] = {};
+    if (scopeNode) {
+      schema = this.resolvePathIntoSchema({
+        path: 'returnValue',
+        scopeNode: scopeNode,
+      });
+    } else {
+      for (const externalFunctionCall of this.externalFunctionCalls) {
+        const functionNameParts = this.splitPath(functionName).map((p) =>
+          this.functionOrScopeName(p),
+        );
+
+        const nameParts = this.splitPath(externalFunctionCall.name).map((p) =>
+          this.functionOrScopeName(p),
+        );
+
+        if (
+          functionNameParts.every((part, index) => part === nameParts[index])
+        ) {
+          for (const schemaPath in externalFunctionCall.schema) {
+            const value1 = schema[schemaPath];
+            const value2 = externalFunctionCall.schema[schemaPath];
+            let bestValue = value1 ?? value2;
+            if (
+              bestValue === 'unknown' ||
+              (bestValue.includes('unknown') && !value2.includes('unknown'))
+            ) {
+              bestValue = value2;
+            }
+            schema[schemaPath] = bestValue;
+          }
+        }
+      }
+    }
+
+    const returnValueSchema = Object.keys(schema)
+      .filter(
+        (key) =>
+          key.startsWith('returnValue') ||
+          (key.indexOf('functionCallReturnValue') > -1 &&
+            (key.indexOf('signature[') === -1 ||
+              key.indexOf('functionCallReturnValue') <
+                key.indexOf('signature['))) ||
+          // Include function paths even if their return value wasn't captured
+          // This ensures methods like onAuthStateChange are included in the schema
+          // But exclude signature entries (they should only be included via functionCallReturnValue paths)
+          (schema[key] === 'function' && key.indexOf('signature[') === -1),
+      )
+      .reduce(
+        (acc, key) => {
+          acc[key] = schema[key];
+
+          const keyParts = this.splitPath(key);
+          for (const path in schema) {
+            const pathParts = this.splitPath(path);
+            if (pathParts.every((p, i) => keyParts[i] === p)) {
+              acc[path] = schema[path];
+            }
+          }
+
+          return acc;
+        },
+        {} as Record<string, string>,
+      );
+
+    // Replace cyScope placeholders with actual callback text
+    const resolvedSchema = this.replaceCyScopePlaceholders(returnValueSchema);
+
+    const tempScopeNode = this.createTempScopeNode(scopeName, resolvedSchema);
+
+    this.validateSchema(tempScopeNode, true, fillInUnknowns);
+
+    return tempScopeNode.schema;
+  }
+
+  /**
+   * Replaces cyScope placeholder references (e.g., cyScope10()) in schema keys
+   * with the actual callback function text from the corresponding scope node.
+   */
+  private replaceCyScopePlaceholders(
+    schema: Record<string, string>,
+  ): Record<string, string> {
+    const cyScopePattern = /cyScope(\d+)\(\)/g;
+    const result: Record<string, string> = {};
+
+    for (const [key, value] of Object.entries(schema)) {
+      let newKey = key;
+
+      // Find all cyScope references in the key
+      const matches = [...key.matchAll(cyScopePattern)];
+      for (const match of matches) {
+        const cyScopeName = `cyScope${match[1]}`;
+        const scopeText = this.findCyScopeText(cyScopeName);
+        if (scopeText) {
+          // Replace cyScope10() with the actual callback text
+          newKey = newKey.replace(match[0], scopeText);
+        }
+      }
+
+      result[newKey] = value;
+    }
+
+    return result;
+  }
+
+  /**
+   * Finds the text for a cyScope by looking up the scope node.
+   * Scope nodes may be named directly (e.g., "cyScope10") or with a parent prefix
+   * (e.g., "ParentScope____cyScope10").
+   * Recursively expands any nested cyScope placeholders within the text.
+   */
+  private findCyScopeText(
+    cyScopeName: string,
+    visited: Set<string> = new Set(),
+  ): string | undefined {
+    // Prevent infinite recursion
+    if (visited.has(cyScopeName)) {
+      return undefined;
+    }
+    visited.add(cyScopeName);
+
+    let scopeText: string | undefined;
+
+    // First try direct lookup
+    if (this.scopeNodes[cyScopeName]) {
+      scopeText = this.scopeNodes[cyScopeName].text;
+    } else {
+      // Then try scope nodes that end with ____cyScopeName
+      for (const scopeNodeName in this.scopeNodes) {
+        if (scopeNodeName.endsWith(`____${cyScopeName}`)) {
+          scopeText = this.scopeNodes[scopeNodeName].text;
+          break;
+        }
+      }
+    }
+
+    if (!scopeText) {
+      return undefined;
+    }
+
+    // Recursively expand any nested cyScope placeholders
+    const cyScopePattern = /cyScope(\d+)\(\)/g;
+    const matches = [...scopeText.matchAll(cyScopePattern)];
+    for (const match of matches) {
+      const nestedCyScopeName = `cyScope${match[1]}`;
+      const nestedText = this.findCyScopeText(nestedCyScopeName, visited);
+      if (nestedText) {
+        scopeText = scopeText.replace(match[0], nestedText);
+      }
+    }
+
+    return scopeText;
+  }
+
+  getEquivalentSignatureVariables() {
+    const scopeNode = this.scopeNodes[this.scopeTree.name];
+
+    const equivalentSignatureVariables: Record<string, string> = {};
+    for (const [path, equivalentValues] of Object.entries(
+      scopeNode.equivalencies,
+    )) {
+      for (const equivalentValue of equivalentValues) {
+        if (path.startsWith('signature[')) {
+          equivalentSignatureVariables[equivalentValue.schemaPath] = path;
+        }
+      }
+    }
+
+    return equivalentSignatureVariables;
+  }
+
+  getVariableInfo(
+    variableName: string,
+    scopeName?: string,
+    final?: boolean,
+  ): VariableInfo | undefined {
+    const scopeNode = this.getScopeOrFunctionCallInfo(
+      scopeName ?? this.scopeTree.name,
+    );
+    if (!scopeNode) return;
+
+    let equivalents = scopeNode.equivalencies[variableName];
+
+    if (!equivalents || equivalents.length === 0) {
+      equivalents = [
+        {
+          id: -1,
+          scopeNodeName: scopeNode.name,
+          schemaPath: variableName,
+          equivalencyReason: 'missing equivalency',
+        },
+      ];
+    }
+
+    const relevantSchema = equivalents.reduce(
+      (acc, eq) => {
+        const relevantSchema = this.getSchema({
+          scopeName: eq.scopeNodeName,
+        });
+
+        if (!relevantSchema) return acc;
+
+        const filterdSchema = this.filterAndConvertSchema({
+          filterPath: eq.schemaPath,
+          newPath: variableName,
+          schema: relevantSchema,
+        });
+
+        return { ...acc, ...filterdSchema };
+      },
+      {} as Record<string, string>,
+    );
+
+    const tempScopeNode = this.createTempScopeNode(
+      scopeName ?? this.scopeTree.name,
+      relevantSchema,
+    );
+
+    this.validateSchema(tempScopeNode, true, final);
+
+    return {
+      name: variableName,
+      equivalentTo: equivalents,
+      schema: tempScopeNode.schema,
+    };
+  }
+
+  getExternalFunctionCalls() {
+    return this.externalFunctionCalls;
+  }
+
+  getEnvironmentVariables() {
+    return this.environmentVariables;
+  }
+
+  toSerializable(): SerializableDataStructure {
+    // Helper to convert ScopeVariable to SerializableScopeVariable
+    const toSerializableVariable = (
+      vars:
+        | ScopeVariable[]
+        | Pick<ScopeVariable, 'scopeNodeName' | 'schemaPath'>[],
+    ): SerializableScopeVariable[] =>
+      vars.map((v) => ({
+        scopeNodeName: v.scopeNodeName,
+        schemaPath: v.schemaPath,
+      }));
+
+    // Helper to get function result for a given function name
+    const getFunctionResult = (
+      functionName?: string,
+    ): SerializableFunctionResult => {
+      return {
+        signature: this.getFunctionSignature({ functionName }) ?? {},
+        signatureWithUnknowns:
+          this.getFunctionSignature({ functionName, fillInUnknowns: true }) ??
+          {},
+        returnValue: this.getReturnValue({ functionName }) ?? {},
+        returnValueWithUnknowns:
+          this.getReturnValue({ functionName, fillInUnknowns: true }) ?? {},
+        usageEquivalencies: Object.entries(
+          this.getUsageEquivalencies(functionName) ?? {},
+        ).reduce(
+          (acc, [key, vars]) => {
+            acc[key] = toSerializableVariable(vars);
+            return acc;
+          },
+          {} as Record<string, SerializableScopeVariable[]>,
+        ),
+        sourceEquivalencies: Object.entries(
+          this.getSourceEquivalencies(functionName) ?? {},
+        ).reduce(
+          (acc, [key, vars]) => {
+            acc[key] = toSerializableVariable(vars);
+            return acc;
+          },
+          {} as Record<string, SerializableScopeVariable[]>,
+        ),
+        environmentVariables: this.getEnvironmentVariables(),
+      };
+    };
+
+    // Convert external function calls
+    const externalFunctionCalls: SerializableFunctionCallInfo[] =
+      this.externalFunctionCalls.map((efc) => ({
+        name: efc.name,
+        callSignature: efc.callSignature,
+        callScope: efc.callScope,
+        schema: efc.schema,
+        equivalencies: efc.equivalencies
+          ? Object.entries(efc.equivalencies).reduce(
+              (acc, [key, vars]) => {
+                acc[key] = toSerializableVariable(vars);
+                return acc;
+              },
+              {} as Record<string, SerializableScopeVariable[]>,
+            )
+          : undefined,
+      }));
+
+    // Get root function result
+    const rootFunction = getFunctionResult();
+
+    // Get results for each external function
+    const functionResults: Record<string, SerializableFunctionResult> = {};
+    for (const efc of this.externalFunctionCalls) {
+      functionResults[efc.name] = getFunctionResult(efc.name);
+    }
+
+    // Get equivalent signature variables
+    const equivalentSignatureVariables = this.getEquivalentSignatureVariables();
+
+    const environmentVariables = this.getEnvironmentVariables();
+
+    return {
+      externalFunctionCalls,
+      rootFunction,
+      functionResults,
+      equivalentSignatureVariables,
+      environmentVariables,
+    };
+  }
+}