@codeyam/codeyam-cli 0.1.0-staging.09652b8 → 0.1.0-staging.28f73cf

package/packages/ai/src/lib/dataStructure/ScopeDataStructure.js

@@ -1,77 +1,214 @@
-/* ScopeDataStructure
+/**
+ * ScopeDataStructure
  *
- * The ScopeDateStructure takes the output of the ASTAnalyzer and merges
- * all scopes to determine a complete schema for the function.
+ * The core engine for CodeYam's static analysis. Takes AST analysis output and
+ * determines the complete data schema for a function by tracking how data flows
+ * through the code.
  *
- * It does two passes through all scopes.
+ * ## High-Level Architecture
  *
- * The first establishes equivalencies,
- * such as implicit parent scope -> nested child scope equivalencies.
+ * ```
+ * ┌─────────────────┐     ┌─────────────────────────────────────────────┐
+ * │  AST Analyzer   │────▶│           ScopeDataStructure                │
+ * │ (per-scope)     │     │                                             │
+ * └─────────────────┘     │  Phase 1: Discovery (onlyEquivalencies)     │
+ *                         │  ├─ Process each scope's analysis           │
+ *                         │  ├─ Build equivalency relationships         │
+ *                         │  └─ Track nested scope hierarchy            │
+ *                         │                                             │
+ *                         │  Phase 2: Schema Building                   │
+ *                         │  ├─ Follow all equivalencies                │
+ *                         │  ├─ Build complete schemas at data sources  │
+ *                         │  └─ Populate equivalencyDatabase            │
+ *                         └─────────────────────────────────────────────┘
+ *                                           │
+ *                                           ▼
+ *                         ┌─────────────────────────────────────────────┐
+ *                         │              Output                          │
+ *                         │  • Function signature schemas               │
+ *                         │  • Return value types                       │
+ *                         │  • External API call schemas                │
+ *                         │  • Data flow (source → usage) mappings      │
+ *                         └─────────────────────────────────────────────┘
+ * ```
  *
- * 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.
+ * ## Key Concepts
  *
- * 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.
+ * ### Equivalencies
+ * When code assigns one variable to another (`const user = props.user`), we create
+ * an "equivalency" linking the two paths. Following these links lets us trace data
+ * back to its source (function arguments or API returns).
+ *
+ * ### Schema Paths
+ * Dot-separated strings describing data structure:
+ * - `signature[0].user.id` - First arg's user.id property
+ * - `items[].name` - name property of array elements
+ * - `functionCallReturnValue(fetch).data` - Return from fetch() call
+ *
+ * ### Two-Phase Processing
+ * 1. **Phase 1 (Discovery)**: `onlyEquivalencies = true`
+ *    - Processes scopes, builds equivalency graph
+ *    - Does NOT populate schemas yet
+ *
+ * 2. **Phase 2 (Schema Building)**: `captureCompleteSchema()`
+ *    - Follows equivalencies to build complete schemas
+ *    - Populates `equivalencyDatabase` for source/usage queries
+ *
+ * ## Key Methods (Entry Points)
+ *
+ * - `constructor(scopeName, scopeText, managers, scopeAnalysis)` - Initialize with root scope
+ * - `addScopeAnalysis(scopeName, text, analysis)` - Add nested scope
+ * - `captureCompleteSchema()` - Trigger Phase 2 processing
+ * - `getSchema({scopeName})` - Get schema for a scope
+ * - `getFunctionSignature({functionName})` - Get function signature schema
+ * - `getSourceEquivalencies()` - Find where data comes from
+ * - `getUsageEquivalencies()` - Find where data is used
+ *
+ * ## Debugging Tips
+ *
+ * - Enable metrics: `addToSchemaCallCount`, `followEquivalenciesCallCount`
+ * - Check `scopeNode.equivalencies` for raw equivalency data
+ * - Use `getEquivalenciesDatabaseEntry(scope, path)` to trace a specific path
+ * - The `visitedTracker` prevents infinite loops - if data is missing, check if
+ *   it was already visited with a different value
+ *
+ * ## Related Files
+ *
+ * - `helpers/` - Extracted utility modules (PathManager, VisitedTracker, etc.)
+ * - `equivalencyManagers/` - Plugins that create equivalencies from AST patterns
+ * - `helpers/README.md` - Overview of the helper module architecture
  */
-import { joinParenthesesAndArrays, splitOutsideParenthesesAndArrays, } from "../splitOutsideParentheses.js";
 import fillInSchemaGapsAndUnknowns from "./helpers/fillInSchemaGapsAndUnknowns.js";
 import ensureSchemaConsistency from "./helpers/ensureSchemaConsistency.js";
-import cleanOutBoundary from "../cleanOutBoundary.js";
 import cleanPath from "./helpers/cleanPath.js";
+import { PathManager } from "./helpers/PathManager.js";
+import { uniqueId, uniqueScopeVariables, uniqueScopeAndPaths, } from "./helpers/uniqueIdUtils.js";
+import selectBestValue from "./helpers/selectBestValue.js";
+import { VisitedTracker } from "./helpers/VisitedTracker.js";
+import { DebugTracer } from "./helpers/DebugTracer.js";
+import { BatchSchemaProcessor } from "./helpers/BatchSchemaProcessor.js";
+import { ScopeTreeManager, ROOT_SCOPE_NAME, } from "./helpers/ScopeTreeManager.js";
 import cleanScopeNodeName from "./helpers/cleanScopeNodeName.js";
 import getFunctionCallRoot from "./helpers/getFunctionCallRoot.js";
 import cleanPathOfNonTransformingFunctions from "./helpers/cleanPathOfNonTransformingFunctions.js";
 import { arrayMethodsSet } from "./helpers/cleanNonObjectFunctions.js";
-const ROOT_SCOPE_NAME = 'root';
 // DEBUG: Performance metrics
 export let maxEquivalencyChainDepth = 0;
 export let addToSchemaCallCount = 0;
 export let followEquivalenciesCallCount = 0;
+export let followEquivalenciesEarlyExitCount = 0;
+export let followEquivalenciesEarlyExitPhase1Count = 0;
+export let followEquivalenciesWithWorkCount = 0;
 export let addEquivalencyCallCount = 0;
 export function resetScopeDataStructureMetrics() {
     maxEquivalencyChainDepth = 0;
     addToSchemaCallCount = 0;
     followEquivalenciesCallCount = 0;
+    followEquivalenciesEarlyExitCount = 0;
+    followEquivalenciesEarlyExitPhase1Count = 0;
+    followEquivalenciesWithWorkCount = 0;
     addEquivalencyCallCount = 0;
 }
+// Performance: Pre-computed Sets for equivalency reason filtering (O(1) vs O(n))
+const ALLOWED_EQUIVALENCY_REASONS = new Set([
+    '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',
+    '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',
+    '.map() function deconstruction',
+    'useMemo return value equivalent to first argument return value',
+    'useState value equivalency',
+    'Node .then() equivalency',
+    'Explicit array deconstruction equivalency value',
+    'forwardRef equivalency',
+    'forwardRef signature to child signature equivalency',
+    'captured function call return value equivalency',
+    'original equivalency - rerouted via useCallback',
+    'non-object function argument function signature equivalency1 - rerouted via useCallback',
+    'non-object function argument function signature equivalency2 - rerouted via useCallback',
+    'implicit parent equivalency - rerouted via useCallback',
+    'Spread operator equivalency key update: implicit parent equivalency',
+    'Array.from() equivalency',
+    'propagated sub-property equivalency',
+    'propagated function call return sub-property equivalency',
+    'where was this function called from', // Added: tracks which scope called an external function
+]);
+const SILENTLY_IGNORED_EQUIVALENCY_REASONS = new Set([
+    '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',
+]);
 export class ScopeDataStructure {
+    // Getter for backward compatibility - returns the tree structure
+    get scopeTree() {
+        return this.scopeTreeManager.getTree();
+    }
     constructor(managers, scopeName = ROOT_SCOPE_NAME, scopeText, scopeAnalysis) {
         this.debugCount = 0;
         this.onlyEquivalencies = true;
         this.equivalencyManagers = [];
         this.scopeNodes = {};
-        this.scopeTree = { name: ROOT_SCOPE_NAME, children: [] };
+        this.scopeTreeManager = new ScopeTreeManager();
         this.externalFunctionCalls = [];
         this.environmentVariables = [];
         this.equivalencyDatabase = [];
+        /**
+         * Conditional usages collected during AST analysis.
+         * Maps local variable path to array of usages.
+         */
+        this.rawConditionalUsages = {};
         this.lastAddToSchemaId = 0;
         this.lastEquivalencyId = 0;
         this.lastEquivalencyDatabaseId = 0;
-        this.pathPartsCache = new Map();
-        this.pathJoinCache = new Map();
+        this.pathManager = new PathManager();
+        this.visitedTracker = new VisitedTracker();
         this.equivalencyDatabaseCache = new Map();
         // Inverted index: maps uniqueId -> EquivalencyDatabaseEntry for O(1) lookup
         this.intermediatesOrderIndex = new Map();
-        this.globalVisited = new Set();
-        // Separate visited set for addComplexSourcePathVariables - uses scope::path only (not value)
-        // This allows addComplexSourcePathVariables to run for each unique scope+path combo,
-        // while the main globalVisited uses scope+path+value for fine-grained deduplication
-        this.complexSourceVisited = new Set();
+        // Index for O(1) lookup of external function calls by name
+        // Invalidated by setting to null; rebuilt lazily on next access
+        this.externalFunctionCallsIndex = null;
+        // Debug tracer for selective path/scope tracing
+        // Enable via: CODEYAM_DEBUG=true CODEYAM_DEBUG_PATHS="user.*,signature" npm test
+        this.tracer = new DebugTracer({
+            enabled: process.env.CODEYAM_DEBUG === 'true',
+            pathPatterns: process.env.CODEYAM_DEBUG_PATHS
+                ? process.env.CODEYAM_DEBUG_PATHS.split(',').map((p) => new RegExp(p))
+                : [],
+            scopePatterns: process.env.CODEYAM_DEBUG_SCOPES
+                ? process.env.CODEYAM_DEBUG_SCOPES.split(',').map((p) => new RegExp(p))
+                : [],
+            maxDepth: 20,
+        });
+        // Batch processor for converting recursive addToSchema calls to iterative processing
+        // This eliminates deep recursion and allows for better work deduplication
+        this.batchProcessor = null;
+        // Track items already in the batch queue to prevent duplicates
+        // For external function calls, uses path-only keys (no value) for more aggressive deduplication
+        this.batchQueuedSet = null;
         this.equivalencyManagers.push(...managers);
-        this.scopeTree.name = scopeName;
+        this.scopeTreeManager.setRootName(scopeName);
         this.addScopeAnalysis(scopeName, scopeText, scopeAnalysis);
     }
     addScopeAnalysis(scopeNodeName, scopeText, scopeAnalysis, parentScopeName, isStatic) {
         try {
-            if (scopeNodeName !== this.scopeTree.name && !parentScopeName) {
-                parentScopeName = this.scopeTree.name;
+            if (scopeNodeName !== this.scopeTreeManager.getRootName() &&
+                !parentScopeName) {
+                parentScopeName = this.scopeTreeManager.getRootName();
             }
             let tree = [];
             if (parentScopeName) {
@@ -112,7 +249,7 @@ export class ScopeDataStructure {
         }
         catch (error) {
             console.log('CodeYam Error: Failed to add scope analysis for scope:', JSON.stringify({
-                rootScopeName: this.scopeTree.name,
+                rootScopeName: this.scopeTreeManager.getRootName(),
                 scopeNodeName,
                 scopeNodeText: scopeText,
                 isolatedStructure: scopeAnalysis.isolatedStructure,
@@ -121,26 +258,46 @@ export class ScopeDataStructure {
             throw error;
         }
     }
+    /**
+     * Phase 2: Build complete schemas by following all equivalencies.
+     *
+     * This is the main entry point for schema building. Call this after all
+     * scopes have been added via `addScopeAnalysis()`.
+     *
+     * ## What Happens
+     *
+     * 1. Resets state (visited tracker, schemas, database)
+     * 2. For each scope, follows equivalencies to build complete schemas
+     * 3. Filters out internal function calls (keeps only external-facing)
+     * 4. Propagates source/usage relationships for querying
+     *
+     * ## After Calling
+     *
+     * You can then use:
+     * - `getSchema()` - Get the built schema for a scope
+     * - `getSourceEquivalencies()` - Find where data comes from
+     * - `getUsageEquivalencies()` - Find where data is used
+     */
     async captureCompleteSchema() {
+        // Reset state for Phase 2
         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([]);
+        this.equivalencyDatabaseCache.clear();
+        this.intermediatesOrderIndex.clear();
+        this.visitedTracker.resetGlobalVisited();
         for (const externalFunctionCall of this.externalFunctionCalls) {
             externalFunctionCall.schema = {};
         }
-        // for (const scopeNode of Object.values(this.scopeNodes)) {
+        // Build schemas for all scopes in parallel
         await Promise.all(Object.values(this.scopeNodes).map(async (scopeNode) => {
             scopeNode.schema = {};
             await this.determineEquivalenciesAndBuildSchema(scopeNode);
         }));
-        // }
         const validExternalFacingScopeNames = new Set([
-            this.scopeTree.name,
+            this.scopeTreeManager.getRootName(),
         ]);
         this.externalFunctionCalls = this.externalFunctionCalls.filter((efc) => {
-            const efcName = efc.name.split('<')[0];
+            const efcName = this.pathManager.stripGenerics(efc.name);
             for (const manager of this.equivalencyManagers) {
                 if (manager.internalFunctions.has(efcName)) {
                     return false;
@@ -149,43 +306,67 @@ export class ScopeDataStructure {
             validExternalFacingScopeNames.add(efcName);
             return true;
         });
+        this.invalidateExternalFunctionCallsIndex();
+        // Pre-compute array methods list once (avoids Array.from() in hot loop)
+        const arrayMethodsList = Array.from(arrayMethodsSet);
+        const containsArrayMethod = (path) => arrayMethodsList.some((method) => path.includes(`.${method}(`));
         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]);
+            entry.usages = entry.usages.filter((usage) => {
+                const baseName = this.pathManager.stripGenerics(usage.scopeNodeName);
+                return (validExternalFacingScopeNames.has(baseName) &&
+                    (usage.schemaPath.startsWith('returnValue') ||
+                        usage.schemaPath.startsWith(baseName)) &&
+                    !containsArrayMethod(usage.schemaPath));
+            });
+            entry.sourceCandidates = entry.sourceCandidates.filter((candidate) => {
+                const baseName = this.pathManager.stripGenerics(candidate.scopeNodeName);
+                return (validExternalFacingScopeNames.has(baseName) &&
+                    (candidate.schemaPath.startsWith('signature[') ||
+                        candidate.schemaPath.startsWith(baseName)) &&
+                    !containsArrayMethod(candidate.schemaPath));
+            });
+        }
+        this.propagateSourceAndUsageEquivalencies(this.scopeNodes[this.scopeTreeManager.getRootName()]);
         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))
         }
     }
+    /**
+     * Core method: Adds a path/value to a scope's schema and follows equivalencies.
+     *
+     * This is the heart of schema building. For each path, it:
+     * 1. Validates the path and checks if already visited
+     * 2. Adds the path → value mapping to the scope's schema
+     * 3. Follows any equivalencies to propagate the schema to linked paths
+     * 4. Tracks the equivalency chain for source/usage database
+     *
+     * ## Cycle Detection
+     *
+     * Uses `visitedTracker.checkAndMarkGlobalVisited()` to prevent infinite loops.
+     * A path is considered visited if the exact (scope, path, value) tuple has
+     * been processed before.
+     *
+     * ## Equivalency Following
+     *
+     * When a path has equivalencies (e.g., `user` → `props.user`), this method
+     * recursively calls itself to add the equivalent path to its scope's schema.
+     *
+     * @param path - Schema path to add (e.g., 'user.id')
+     * @param value - Type value (e.g., 'string', 'number')
+     * @param scopeNode - The scope to add to
+     * @param equivalencyValueChain - Tracks the chain for database population
+     * @param traceId - Debug ID for tracing specific paths
+     */
     addToSchema({ path, value, scopeNode, equivalencyValueChain = [], traceId, }) {
         addToSchemaCallCount++;
-        // DEBUG: Detect infinite loops
+        // Trace entry for debugging
+        this.tracer.traceEnter('addToSchema', {
+            path,
+            scope: scopeNode?.name,
+            value,
+            chainDepth: equivalencyValueChain.length,
+        });
+        // Safety: Detect runaway recursion
         if (addToSchemaCallCount > 500000) {
             console.error('INFINITE LOOP DETECTED in addToSchema', {
                 callCount: addToSchemaCallCount,
@@ -199,14 +380,16 @@ export class ScopeDataStructure {
         if (equivalencyValueChain.length > maxEquivalencyChainDepth) {
             maxEquivalencyChainDepth = equivalencyValueChain.length;
         }
-        if (!scopeNode)
+        if (!scopeNode) {
             return;
+        }
         if (!this.isValidPath(path)) {
             if (traceId) {
                 console.info('Debug propagation: not a valid path', { path, traceId });
             }
             return;
         }
+        // Update chain metadata for database tracking
         if (equivalencyValueChain.length > 0) {
             equivalencyValueChain[equivalencyValueChain.length - 1].addToSchemaId =
                 ++this.lastAddToSchemaId;
@@ -216,88 +399,35 @@ export class ScopeDataStructure {
                 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');
-        // }
+        // Debug level: 0=minimal, 1=executed paths, 2=all paths (set via traceId)
+        const debugLevel = 0;
+        // ─────────────────────────────────────────────────────────────────────────
+        // SECTION 1: Handle complex source paths (paths with multiple data origins)
+        // ─────────────────────────────────────────────────────────────────────────
         const equivalenciesDatabaseEntry = this.getEquivalenciesDatabaseEntry(scopeNode.name, path);
-        // Call addComplexSourcePathVariables like the original code (before visited check)
+        // Process complex source paths (before visited check, per original design)
         this.addComplexSourcePathVariables(equivalenciesDatabaseEntry, scopeNode, path, equivalencyValueChain, traceId);
-        const uniqueIdentifier = `${scopeNode.name}::${path}::${value}`;
-        if (this.globalVisited.has(uniqueIdentifier)) {
+        // ─────────────────────────────────────────────────────────────────────────
+        // SECTION 2: Cycle detection - skip if already visited with this value
+        // ─────────────────────────────────────────────────────────────────────────
+        if (this.visitedTracker.checkAndMarkGlobalVisited(scopeNode.name, path, value)) {
             if (traceId) {
-                console.info('Debug propagation: already globally visited path', JSON.stringify({
-                    uniqueIdentifier,
-                    // equivalencyValueChain,
-                }, null, 2));
+                console.info('Debug: already visited', {
+                    key: `${scopeNode.name}::${path}::${value}`,
+                });
             }
+            // Still record in database even if visited (captures full chain)
             if (!this.onlyEquivalencies) {
                 this.addToEquivalencyDatabase(equivalencyValueChain, traceId);
             }
             return;
         }
-        this.globalVisited.add(uniqueIdentifier);
+        // Continue complex source processing after visited check
         this.captureComplexSourcePaths(equivalenciesDatabaseEntry, scopeNode, path, equivalencyValueChain, traceId);
+        // ─────────────────────────────────────────────────────────────────────────
+        // SECTION 3: Process each subpath to follow equivalencies
+        // For path "user.profile.name", processes: "user", "user.profile", "user.profile.name"
+        // ─────────────────────────────────────────────────────────────────────────
         const pathParts = this.splitPath(path);
         this.checkForArrayItemPath(pathParts, scopeNode, equivalencyValueChain);
         let propagated = false;
@@ -385,45 +515,42 @@ export class ScopeDataStructure {
                 }
             }
         }
+        // ─────────────────────────────────────────────────────────────────────────
+        // SECTION 4: Write to schema if appropriate
+        // Only writes if: (a) path not set or is 'unknown', AND
+        //                 (b) path belongs to this scope (instantiated, signature, or return)
+        // ─────────────────────────────────────────────────────────────────────────
         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
+        // Early exit if schema already has this exact value
         if (scopeNode.schema[path] === value && value !== 'unknown') {
             return;
         }
         if (writeToCurrentScopeSchema) {
             if (traceId && debugLevel > 0) {
-                console.info('Debug Propagation: currentScope executed', {
-                    traceId,
+                console.info('Debug: writing schema', {
                     path,
-                    pathParts,
-                    scopeNodeName: scopeNode.name,
+                    value,
+                    scope: scopeNode.name,
                 });
             }
             scopeNode.schema[path] = value;
         }
+        // ─────────────────────────────────────────────────────────────────────────
+        // SECTION 5: Record in equivalency database (Phase 2 only)
+        // ─────────────────────────────────────────────────────────────────────────
         if (!this.onlyEquivalencies) {
             this.addToEquivalencyDatabase(equivalencyValueChain, traceId);
         }
         if (traceId) {
-            console.info('Debug Propagation: exiting', JSON.stringify({
-                traceId,
-                scopeNodeName: scopeNode.name,
+            console.info('Debug: addToSchema complete', {
+                scope: 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, schema = {}, scopeName) {
@@ -444,52 +571,16 @@ export class ScopeDataStructure {
             });
             throw new Error(`Infinite loop detected: addEquivalency called ${addEquivalencyCallCount} times`);
         }
-        // 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',
-            'propagated sub-property equivalency',
-            'propagated function call return sub-property 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)) {
+        // Filter equivalency reasons - use pre-computed Sets for O(1) lookup
+        if (!ALLOWED_EQUIVALENCY_REASONS.has(equivalencyReason)) {
+            if (SILENTLY_IGNORED_EQUIVALENCY_REASONS.has(equivalencyReason)) {
                 return;
             }
             else {
+                // Log and skip - if an equivalency reason isn't in ALLOWED or SILENTLY_IGNORED,
+                // it shouldn't be stored (was previously missing the return)
                 console.info('Not tracked equivalency reason', { equivalencyReason });
+                return;
             }
         }
         if (!equivalentScopeName) {
@@ -618,7 +709,8 @@ export class ScopeDataStructure {
             if (!functionCallInfo.equivalencies) {
                 functionCallInfo.equivalencies = {};
             }
-            const existingFunctionCall = this.externalFunctionCalls.find((fc) => getFunctionCallRoot(functionCallInfo.callSignature) === fc.name);
+            const searchKey = getFunctionCallRoot(functionCallInfo.callSignature);
+            const existingFunctionCall = this.getExternalFunctionCallsIndex().get(searchKey);
             if (existingFunctionCall) {
                 existingFunctionCall.schema = {
                     ...existingFunctionCall.schema,
@@ -635,6 +727,7 @@ export class ScopeDataStructure {
                     !callingScopeNode.parentInstantiatedVariables?.includes(functionCallInfoNameParts[0]);
                 if (isExternal) {
                     this.externalFunctionCalls.push(functionCallInfo);
+                    this.invalidateExternalFunctionCallsIndex();
                 }
             }
         }
@@ -656,7 +749,7 @@ export class ScopeDataStructure {
         //   );
         // }
         const getRootOrExternalFunctionCallInfo = (name) => {
-            return name === this.scopeTree.name
+            return name === this.scopeTreeManager.getRootName()
                 ? this.getScopeNode()
                 : this.getExternalFunctionCallInfo(name);
         };
@@ -674,82 +767,49 @@ export class ScopeDataStructure {
                     schemaPath === safePath ||
                     safePath.startsWith(schemaPath));
             });
+            // PERF: Build a Map for O(1) lookup instead of O(n) inner loop
+            // Map from "remaining parts joined" to equivalentSchemaPath
+            const equivalentSchemaPathMap = new Map();
+            for (const equivalentSchemaPath of Object.keys(equivalentScopeNode.schema)) {
+                // Quick string check before expensive path splitting
+                if (!(equivalentSchemaPath.startsWith(equivalentPath) ||
+                    equivalentSchemaPath === equivalentPath ||
+                    equivalentPath.startsWith(equivalentSchemaPath))) {
+                    continue;
+                }
+                const equivalentSchemaPathParts = this.splitPath(equivalentSchemaPath);
+                if (!equivalentPathParts.every((p, i) => equivalentSchemaPathParts[i] === p)) {
+                    continue;
+                }
+                const remainingEquivalentSchemaPathParts = equivalentSchemaPathParts.slice(equivalentPathParts.length);
+                // Use | as separator since it won't appear in path parts
+                const key = remainingEquivalentSchemaPathParts.join('|');
+                equivalentSchemaPathMap.set(key, equivalentSchemaPath);
+            }
             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;
+                // PERF: O(1) Map lookup instead of O(n) inner loop
+                const remainingKey = remainingSchemaPathParts.join('|');
+                const equivalentSchemaPath = equivalentSchemaPathMap.get(remainingKey);
+                if (equivalentSchemaPath) {
                     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;
-                    }
+                    const bestValue = selectBestValue(value1, 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))) {
+                else if (scopeNode.name.includes('____cyScope') ||
+                    !('instantiatedVariables' in equivalentScopeNode)) {
+                    // No matching equivalent path found - create one if needed
                     // 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];
                 }
@@ -772,83 +832,26 @@ export class ScopeDataStructure {
         }
     }
     splitPath(path) {
-        if (this.pathPartsCache.has(path)) {
-            return structuredClone(this.pathPartsCache.get(path));
-        }
-        const pathParts = splitOutsideParenthesesAndArrays(path);
-        this.pathPartsCache.set(path, structuredClone(pathParts));
-        return pathParts;
+        return this.pathManager.splitPath(path);
     }
     joinPathParts(pathParts) {
-        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;
+        return this.pathManager.joinPathParts(pathParts);
     }
     // PRIVATE METHODS //
-    uniqueId({ scopeNodeName, schemaPath, value, }) {
-        const parts = [scopeNodeName, schemaPath, value].filter(Boolean);
-        return parts.join('::');
+    uniqueId(params) {
+        return uniqueId(params);
     }
     uniqueScopeVariables(scopeVariables) {
-        return this.uniqueScopeAndPaths(scopeVariables);
+        return uniqueScopeVariables(scopeVariables);
     }
     uniqueScopeAndPaths(scopeVariables) {
-        if (!scopeVariables || scopeVariables.length === 0)
-            return [];
-        // Optimize from O(n²) to O(n) using Set for deduplication
-        const seen = new Set();
-        return scopeVariables.filter((varItem) => {
-            const key = `${varItem.scopeNodeName}::${varItem.schemaPath}`;
-            if (seen.has(key)) {
-                return false;
-            }
-            seen.add(key);
-            return true;
-        });
+        return uniqueScopeAndPaths(scopeVariables);
     }
     isValidPath(path) {
-        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;
-        });
+        return this.pathManager.isValidPath(path);
     }
     addToTree(pathParts) {
-        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: [],
-                };
-                scopeTreeNode.children.push(childScopeTreeNode);
-                scopeTreeNode = childScopeTreeNode;
-            }
-        }
+        this.scopeTreeManager.addPath(pathParts);
     }
     setInstantiatedVariables(scopeNode) {
         let instantiatedVariables = scopeNode.analysis?.instantiatedVariables ?? [];
@@ -947,12 +950,15 @@ export class ScopeDataStructure {
                 }
             }
         }
+        // PERF: Enable batch processing to convert recursive addToSchema calls to iterative
+        // This eliminates deep call stacks and improves deduplication
+        this.batchProcessor = new BatchSchemaProcessor();
+        this.batchQueuedSet = new Set();
         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,
@@ -965,19 +971,39 @@ export class ScopeDataStructure {
                     },
                 ],
             });
-            // 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,
-            //   });
-            // }
-        }
+            // Process any work queued by followEquivalencies
+            this.processBatchQueue();
+        }
+        // Final pass to ensure all queued work is processed
+        this.processBatchQueue();
+        // Clean up batch processor
+        this.batchProcessor = null;
+        this.batchQueuedSet = null;
         this.validateSchema(scopeNode, false, false);
     }
+    /**
+     * Process all items in the batch queue.
+     * Each item may queue more work via followEquivalencies.
+     */
+    processBatchQueue() {
+        if (!this.batchProcessor)
+            return;
+        while (this.batchProcessor.hasWork()) {
+            const item = this.batchProcessor.getNextWork();
+            if (!item)
+                break;
+            const scopeNode = this.getScopeOrFunctionCallInfo(item.scopeNodeName);
+            if (!scopeNode)
+                continue;
+            this.addToSchema({
+                path: item.path,
+                value: item.value,
+                scopeNode,
+                equivalencyValueChain: item.equivalencyValueChain,
+                traceId: item.traceId,
+            });
+        }
+    }
     /**
      * Propagates returnValue.* sub-properties from a callback scope to the usage path.
      *
@@ -1155,11 +1181,11 @@ export class ScopeDataStructure {
         }
     }
     checkForArrayItemPath(pathParts, scopeNode, equivalencyValueChain) {
-        const arrayItemPath = joinParenthesesAndArrays([...pathParts, '[]']);
+        const arrayItemPath = this.joinPathParts([...pathParts, '[]']);
         if (scopeNode.equivalencies[arrayItemPath]) {
             const firstEquivalency = equivalencyValueChain[0].currentPath;
-            const newFirstEquivalencyPath = joinParenthesesAndArrays([
-                ...splitOutsideParenthesesAndArrays(firstEquivalency.schemaPath),
+            const newFirstEquivalencyPath = this.joinPathParts([
+                ...this.splitPath(firstEquivalency.schemaPath),
                 '[]',
             ]);
             this.addToSchema({
@@ -1176,27 +1202,77 @@ export class ScopeDataStructure {
             });
         }
     }
+    /**
+     * Follows equivalencies for a subpath and recursively calls addToSchema.
+     *
+     * This is the recursive heart of schema propagation. When we have:
+     *   `user` equivalent to `props.user`
+     * And we're processing `user.id`, this method will:
+     * 1. Find the equivalency `user` → `props.user`
+     * 2. Reconstruct the full path: `props.user.id`
+     * 3. Recursively call addToSchema for the equivalent scope
+     *
+     * ## Function-Ambivalent Paths
+     *
+     * Handles paths like `data.map(fn)` by also checking equivalencies
+     * for `data.map` (without the function argument). This allows
+     * array method chains to propagate correctly.
+     *
+     * @param scopeNode - Current scope being processed
+     * @param path - Full original path (e.g., 'user.profile.name')
+     * @param pathParts - Split version of path
+     * @param subPath - Current subpath being checked (e.g., 'user.profile')
+     * @param subPathParts - Split version of subPath
+     * @param value - Type value to propagate
+     * @param equivalencyValueChain - Chain tracking for database
+     * @param traceId - Debug ID
+     * @param debugLevel - 0=minimal, 1=executed, 2=verbose
+     */
     followEquivalencies(scopeNode, path, pathParts, subPath, subPathParts, value, equivalencyValueChain, traceId, debugLevel = 0) {
         followEquivalenciesCallCount++;
+        // Trace for debugging
+        this.tracer.trace('followEquivalencies', {
+            path,
+            scope: scopeNode.name,
+            subPath,
+            hasEquivalencies: (scopeNode.equivalencies[subPath]?.length ?? 0) > 0,
+        });
         let propagated = false;
+        // ─────────────────────────────────────────────────────────────────────────
+        // Step 1: Collect equivalencies (including function-ambivalent paths)
+        // ─────────────────────────────────────────────────────────────────────────
         let equivalentValues = scopeNode.equivalencies[subPath] ?? [];
         let functionAmbivalentSubPath = subPath;
         let functionAmbivalentSubPathParts = subPathParts;
-        if (subPathParts[subPathParts.length - 1].indexOf('(') > -1) {
+        // For paths like `data.map(fn)`, also check `data.map` equivalencies
+        // PERF: Only do the expensive function-ambivalent processing if:
+        // 1. No equivalencies found yet, AND
+        // 2. The subpath ends with a function call (contains '(')
+        const lastPart = subPathParts[subPathParts.length - 1];
+        if (lastPart.indexOf('(') > -1) {
+            // Check function-ambivalent path for equivalencies
             functionAmbivalentSubPathParts = [
                 ...subPathParts.slice(0, -1),
-                subPathParts[subPathParts.length - 1].split('(')[0],
+                lastPart.split('(')[0],
             ];
             functionAmbivalentSubPath = this.joinPathParts(functionAmbivalentSubPathParts);
-            equivalentValues = [
-                ...(equivalentValues ?? []),
-                ...(scopeNode.equivalencies[functionAmbivalentSubPath] ?? []),
-            ];
+            const functionAmbivalentEquivalencies = scopeNode.equivalencies[functionAmbivalentSubPath];
+            if (functionAmbivalentEquivalencies?.length > 0) {
+                equivalentValues = [
+                    ...equivalentValues,
+                    ...functionAmbivalentEquivalencies,
+                ];
+            }
         }
         // Early exit optimization: if no equivalencies to follow, skip expensive processing
         if (equivalentValues.length === 0) {
+            followEquivalenciesEarlyExitCount++;
+            if (this.onlyEquivalencies) {
+                followEquivalenciesEarlyExitPhase1Count++;
+            }
             return false;
         }
+        followEquivalenciesWithWorkCount++;
         if (traceId && debugLevel > 1) {
             console.info('Debug Propagation: equivalence', JSON.stringify({
                 traceId,
@@ -1212,10 +1288,17 @@ export class ScopeDataStructure {
             }, null, 2));
         }
         const uniqueEquivalentValues = this.uniqueScopeVariables(equivalentValues);
+        // PERF: Only create Set when chain is non-empty (common case avoids allocation)
+        // Pre-compute Set of chain IDs for O(1) cycle detection instead of O(n) .some()
+        const chainIdSet = equivalencyValueChain.length > 0
+            ? new Set(equivalencyValueChain.map((ev) => ev.id))
+            : null;
         for (let index = 0; index < uniqueEquivalentValues.length; ++index) {
             const equivalentValue = uniqueEquivalentValues[index];
-            if (equivalentValue.id !== -1 &&
-                equivalencyValueChain.some((ev) => ev.id === equivalentValue.id)) {
+            // O(1) cycle check using Set instead of O(n) .some()
+            if (chainIdSet &&
+                equivalentValue.id !== -1 &&
+                chainIdSet.has(equivalentValue.id)) {
                 if (traceId) {
                     console.info('Debug Propagation: skipping circular equivalence', JSON.stringify({
                         traceId,
@@ -1243,8 +1326,12 @@ export class ScopeDataStructure {
             if (lastRelevantSubPathPart.endsWith(')') &&
                 schemaPathParts[schemaPathParts.length - 1] ===
                     lastRelevantSubPathPart.split('(')[0]) {
-                schemaPathParts[schemaPathParts.length - 1] = lastRelevantSubPathPart;
-                schemaPath = this.joinPathParts(schemaPathParts);
+                // PERF: Don't mutate the array - create a new one to avoid requiring structuredClone
+                const updatedSchemaPathParts = [
+                    ...schemaPathParts.slice(0, -1),
+                    lastRelevantSubPathPart,
+                ];
+                schemaPath = this.joinPathParts(updatedSchemaPathParts);
             }
             const remainingPathParts = pathParts.slice(relevantSubPathParts.length);
             const remainingPath = this.joinPathParts(remainingPathParts);
@@ -1287,23 +1374,27 @@ export class ScopeDataStructure {
                         // 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,
+                // PERF: Use spread instead of structuredClone - the chain items are immutable
+                // so shallow copy is sufficient and much faster (structuredClone is expensive)
+                const localEquivalencyValueChain = [
+                    ...equivalencyValueChain,
+                    {
+                        id: equivalentValue.id,
+                        source: 'equivalence',
+                        previousPath: {
+                            scopeNodeName: scopeNode.name,
+                            schemaPath: path,
+                            value,
+                        },
+                        currentPath: {
+                            scopeNodeName: equivalentScopeNode.name,
+                            schemaPath: newEquivalentPath,
+                            value,
+                        },
+                        reason: equivalentValue.equivalencyReason,
+                        traceId,
                     },
-                    reason: equivalentValue.equivalencyReason,
-                    traceId,
-                });
+                ];
                 // writeEquivalencyToFile(
                 //   scopeNode.name,
                 //   subPath,
@@ -1313,13 +1404,48 @@ export class ScopeDataStructure {
                 //   equivalentValue.equivalencyReason,
                 // )
                 propagated = true;
-                this.addToSchema({
-                    path: newEquivalentPath,
-                    value,
-                    scopeNode: equivalentScopeNode,
-                    equivalencyValueChain: localEquivalencyValueChain,
-                    traceId,
-                });
+                // PERF: If batch processor is active, queue work instead of recursing
+                // This converts deep recursion to iterative processing
+                if (this.batchProcessor) {
+                    // PERF OPTIMIZATION: For external function calls, use path-only key (ignore value)
+                    // External FCs don't have internals to analyze, so processing the same path
+                    // with different values is redundant - we're just tracking data flow
+                    const isExternalFc = equivalentValue.equivalencyReason ===
+                        'equivalency to external function call' ||
+                        this.getExternalFunctionCallInfo(equivalentScopeNode.name) !==
+                            undefined;
+                    const queueKey = isExternalFc
+                        ? `${equivalentScopeNode.name}::${newEquivalentPath}` // path-only for external FC
+                        : `${equivalentScopeNode.name}::${newEquivalentPath}::${value}`; // full key otherwise
+                    // Always check visited - it catches already-processed items
+                    const alreadyVisited = this.visitedTracker.hasGlobalVisited(equivalentScopeNode.name, newEquivalentPath, value);
+                    // For external FCs, queueKey is path-only so this catches any-value duplicates
+                    const alreadyQueued = this.batchQueuedSet?.has(queueKey);
+                    if (alreadyVisited || alreadyQueued) {
+                        // Still record in database to capture the chain (as addToSchema does)
+                        this.addToEquivalencyDatabase(localEquivalencyValueChain, traceId);
+                    }
+                    else {
+                        // Mark as queued to prevent duplicate queue entries
+                        this.batchQueuedSet?.add(queueKey);
+                        this.batchProcessor.addWork({
+                            scopeNodeName: equivalentScopeNode.name,
+                            path: newEquivalentPath,
+                            value,
+                            equivalencyValueChain: localEquivalencyValueChain,
+                            traceId,
+                        });
+                    }
+                }
+                else {
+                    this.addToSchema({
+                        path: newEquivalentPath,
+                        value,
+                        scopeNode: equivalentScopeNode,
+                        equivalencyValueChain: localEquivalencyValueChain,
+                        traceId,
+                    });
+                }
             }
         }
         return propagated;
@@ -1343,11 +1469,9 @@ export class ScopeDataStructure {
                     const usageScopeNode = this.getScopeOrFunctionCallInfo(usageEquivalency.scopeNodeName);
                     // Guard against infinite recursion by tracking which paths we've already
                     // added from addComplexSourcePathVariables
-                    const complexPathKey = `${usageScopeNode.name}::${newUsageEquivalentPath}`;
-                    if (this.complexSourceVisited.has(complexPathKey)) {
+                    if (this.visitedTracker.checkAndMarkComplexSourceVisited(usageScopeNode.name, newUsageEquivalentPath)) {
                         continue;
                     }
-                    this.complexSourceVisited.add(complexPathKey);
                     this.addToSchema({
                         path: newUsageEquivalentPath,
                         value: 'unknown',
@@ -1542,6 +1666,7 @@ export class ScopeDataStructure {
             if (functionScope) {
                 functionScope.functionCalls.push(externalFunctionCallInfo);
                 this.externalFunctionCalls.splice(i, 1);
+                this.invalidateExternalFunctionCallsIndex();
                 for (const equivalentPath in externalFunctionCallInfo.equivalencies) {
                     let localEquivalentPath = equivalentPath;
                     if (localEquivalentPath.startsWith(externalFunctionCallInfo.callSignature)) {
@@ -1584,15 +1709,17 @@ export class ScopeDataStructure {
         for (const key in scopeNode.equivalencies) {
             const keyParts = this.splitPath(key);
             if (keyParts.length > 1) {
-                const lastPart = keyParts.pop();
+                // PERF: Don't mutate the array - use indexing instead of pop() to avoid requiring structuredClone
+                const lastPart = keyParts[keyParts.length - 1];
                 if (lastPart.startsWith('signature[')) {
-                    const functionCall = keyParts[keyParts.length - 1];
+                    const keyPartsWithoutLast = keyParts.slice(0, -1);
+                    const functionCall = keyPartsWithoutLast[keyPartsWithoutLast.length - 1];
                     const argumentsIndex = functionCall.indexOf('(');
                     const functionName = this.joinPathParts([
-                        ...keyParts.slice(0, -1),
+                        ...keyPartsWithoutLast.slice(0, -1),
                         functionCall.slice(0, argumentsIndex === -1 ? undefined : argumentsIndex),
                     ]);
-                    const callSignature = this.joinPathParts(keyParts);
+                    const callSignature = this.joinPathParts(keyPartsWithoutLast);
                     const functionCallInfo = {
                         name: functionName,
                         callSignature,
@@ -1604,15 +1731,17 @@ export class ScopeDataStructure {
             for (const equivalentValues of scopeNode.equivalencies[key]) {
                 const equivalentValueParts = this.splitPath(equivalentValues.schemaPath);
                 if (equivalentValueParts.length > 1) {
-                    const lastPart = equivalentValueParts.pop();
+                    // PERF: Don't mutate the array - use indexing instead of pop() to avoid requiring structuredClone
+                    const lastPart = equivalentValueParts[equivalentValueParts.length - 1];
                     if (lastPart.startsWith('functionCallReturnValue')) {
-                        const functionCall = equivalentValueParts[equivalentValueParts.length - 1];
+                        const partsWithoutLast = equivalentValueParts.slice(0, -1);
+                        const functionCall = partsWithoutLast[partsWithoutLast.length - 1];
                         const argumentsIndex = functionCall.indexOf('(');
                         const functionName = this.joinPathParts([
-                            ...equivalentValueParts.slice(0, -1),
+                            ...partsWithoutLast.slice(0, -1),
                             functionCall.slice(0, argumentsIndex === -1 ? undefined : argumentsIndex),
                         ]);
-                        const callSignature = this.joinPathParts(equivalentValueParts);
+                        const callSignature = this.joinPathParts(partsWithoutLast);
                         const functionCallInfo = {
                             name: functionName,
                             callSignature,
@@ -1757,7 +1886,7 @@ export class ScopeDataStructure {
         return this.getExternalFunctionCallInfo(scopeName);
     }
     getScopeNode(scopeName) {
-        const scopeNode = this.scopeNodes[scopeName ?? this.scopeTree.name];
+        const scopeNode = this.scopeNodes[scopeName ?? this.scopeTreeManager.getRootName()];
         if (scopeNode)
             return scopeNode;
         for (const scopeNodeName in this.scopeNodes) {
@@ -1766,20 +1895,54 @@ export class ScopeDataStructure {
             }
         }
     }
+    /**
+     * Gets or builds the external function calls index for O(1) lookup.
+     * The index maps both the full name and the name without generics to the FunctionCallInfo.
+     */
+    getExternalFunctionCallsIndex() {
+        if (this.externalFunctionCallsIndex === null) {
+            this.externalFunctionCallsIndex = new Map();
+            for (const efc of this.externalFunctionCalls) {
+                this.externalFunctionCallsIndex.set(efc.name, efc);
+                // Also index by name without generics (e.g., 'MyFunction<T>' -> 'MyFunction')
+                const nameWithoutGenerics = this.pathManager.stripGenerics(efc.name);
+                if (nameWithoutGenerics !== efc.name) {
+                    this.externalFunctionCallsIndex.set(nameWithoutGenerics, efc);
+                }
+            }
+        }
+        return this.externalFunctionCallsIndex;
+    }
+    /**
+     * Invalidates the external function calls index.
+     * Call this after any mutation to externalFunctionCalls array.
+     */
+    invalidateExternalFunctionCallsIndex() {
+        this.externalFunctionCallsIndex = null;
+    }
     getExternalFunctionCallInfo(functionName) {
-        return this.externalFunctionCalls.find((efc) => efc.name === getFunctionCallRoot(functionName) ||
-            efc.name.split('<')[0] === getFunctionCallRoot(functionName));
+        const searchKey = getFunctionCallRoot(functionName);
+        const index = this.getExternalFunctionCallsIndex();
+        // First try exact match
+        const exact = index.get(searchKey);
+        if (exact)
+            return exact;
+        // Fallback to the original find for edge cases not covered by index
+        return this.externalFunctionCalls.find((efc) => efc.name === searchKey ||
+            this.pathManager.stripGenerics(efc.name) === searchKey);
     }
     getScopeAnalysis(scopeName) {
-        return this.scopeNodes[scopeName ?? this.scopeTree.name].analysis;
+        return this.scopeNodes[scopeName ?? this.scopeTreeManager.getRootName()]
+            .analysis;
     }
     getAnalysisTree() {
         return this.scopeTree;
     }
     getSchema({ scopeName, fillInUnknowns, }) {
-        const scopeNode = this.scopeNodes[scopeName ?? this.scopeTree.name];
+        const scopeNode = this.scopeNodes[scopeName ?? this.scopeTreeManager.getRootName()];
         if (!scopeNode) {
-            const externalFunctionCallSchema = this.externalFunctionCalls.find((call) => call.name === getFunctionCallRoot(scopeName))?.schema;
+            const searchKey = getFunctionCallRoot(scopeName);
+            const externalFunctionCallSchema = this.getExternalFunctionCallsIndex().get(searchKey)?.schema;
             if (!externalFunctionCallSchema)
                 return;
             return Object.keys(externalFunctionCallSchema).reduce((acc, key) => {
@@ -1802,7 +1965,9 @@ export class ScopeDataStructure {
         if (this.equivalencyDatabaseCache.has(cacheKey)) {
             return this.equivalencyDatabaseCache.get(cacheKey);
         }
-        const result = this.equivalencyDatabase.find((entry) => entry.intermediatesOrder[cacheKey] !== undefined);
+        // PERF: Use inverted index for O(1) lookup instead of O(n) array scan
+        // The intermediatesOrderIndex maps pathId (scopeNodeName::schemaPath) to entry
+        const result = this.intermediatesOrderIndex.get(cacheKey);
         this.equivalencyDatabaseCache.set(cacheKey, result);
         return result;
     }
@@ -1865,12 +2030,12 @@ export class ScopeDataStructure {
                 }
             }
         }
-        const tempScopeNode = this.createTempScopeNode(functionName ?? this.scopeTree.name, signatureInSchema, equivalencies);
+        const tempScopeNode = this.createTempScopeNode(functionName ?? this.scopeTreeManager.getRootName(), signatureInSchema, equivalencies);
         this.validateSchema(tempScopeNode, true, fillInUnknowns);
         return tempScopeNode.schema;
     }
     getReturnValue({ functionName, fillInUnknowns, }) {
-        const scopeName = functionName ?? this.scopeTree.name;
+        const scopeName = functionName ?? this.scopeTreeManager.getRootName();
         const scopeNode = this.scopeNodes[scopeName];
         let schema = {};
         if (scopeNode) {
@@ -1887,12 +2052,7 @@ export class ScopeDataStructure {
                     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;
+                        schema[schemaPath] = selectBestValue(value1, value2, value2);
                     }
                 }
             }
@@ -1989,7 +2149,7 @@ export class ScopeDataStructure {
         return scopeText;
     }
     getEquivalentSignatureVariables() {
-        const scopeNode = this.scopeNodes[this.scopeTree.name];
+        const scopeNode = this.scopeNodes[this.scopeTreeManager.getRootName()];
         const equivalentSignatureVariables = {};
         for (const [path, equivalentValues] of Object.entries(scopeNode.equivalencies)) {
             for (const equivalentValue of equivalentValues) {
@@ -2001,7 +2161,7 @@ export class ScopeDataStructure {
         return equivalentSignatureVariables;
     }
     getVariableInfo(variableName, scopeName, final) {
-        const scopeNode = this.getScopeOrFunctionCallInfo(scopeName ?? this.scopeTree.name);
+        const scopeNode = this.getScopeOrFunctionCallInfo(scopeName ?? this.scopeTreeManager.getRootName());
         if (!scopeNode)
             return;
         let equivalents = scopeNode.equivalencies[variableName];
@@ -2028,7 +2188,7 @@ export class ScopeDataStructure {
             });
             return { ...acc, ...filterdSchema };
         }, {});
-        const tempScopeNode = this.createTempScopeNode(scopeName ?? this.scopeTree.name, relevantSchema);
+        const tempScopeNode = this.createTempScopeNode(scopeName ?? this.scopeTreeManager.getRootName(), relevantSchema);
         this.validateSchema(tempScopeNode, true, final);
         return {
             name: variableName,
@@ -2042,6 +2202,50 @@ export class ScopeDataStructure {
     getEnvironmentVariables() {
         return this.environmentVariables;
     }
+    /**
+     * Add conditional usages from AST analysis.
+     * Called during scope analysis to collect all conditionals.
+     */
+    addConditionalUsages(usages) {
+        for (const [path, pathUsages] of Object.entries(usages)) {
+            if (!this.rawConditionalUsages[path]) {
+                this.rawConditionalUsages[path] = [];
+            }
+            // Deduplicate usages
+            for (const usage of pathUsages) {
+                const exists = this.rawConditionalUsages[path].some((existing) => existing.location === usage.location &&
+                    existing.conditionType === usage.conditionType &&
+                    JSON.stringify(existing.comparedValues) ===
+                        JSON.stringify(usage.comparedValues));
+                if (!exists) {
+                    this.rawConditionalUsages[path].push(usage);
+                }
+            }
+        }
+    }
+    /**
+     * Get enriched conditional usages with source tracing.
+     * Uses explainPath to trace each local variable back to its data source.
+     */
+    getEnrichedConditionalUsages() {
+        const enriched = {};
+        for (const [path, usages] of Object.entries(this.rawConditionalUsages)) {
+            // Try to trace this path back to a data source
+            // First, try the root scope
+            const rootScopeName = this.scopeTreeManager.getTree().name;
+            const explanation = this.explainPath(rootScopeName, path);
+            let sourceDataPath;
+            if (explanation.source) {
+                // Build the full data path: scopeName.path
+                sourceDataPath = `${explanation.source.scope}.${explanation.source.path}`;
+            }
+            enriched[path] = usages.map((usage) => ({
+                ...usage,
+                sourceDataPath,
+            }));
+        }
+        return enriched;
+    }
     toSerializable() {
         // Helper to convert ScopeVariable to SerializableScopeVariable
         const toSerializableVariable = (vars) => vars.map((v) => ({
@@ -2090,13 +2294,427 @@ export class ScopeDataStructure {
         // Get equivalent signature variables
         const equivalentSignatureVariables = this.getEquivalentSignatureVariables();
         const environmentVariables = this.getEnvironmentVariables();
+        // Get enriched conditional usages with source tracing
+        const enrichedConditionalUsages = this.getEnrichedConditionalUsages();
+        const conditionalUsages = Object.keys(enrichedConditionalUsages).length > 0
+            ? enrichedConditionalUsages
+            : undefined;
         return {
             externalFunctionCalls,
             rootFunction,
             functionResults,
             equivalentSignatureVariables,
             environmentVariables,
+            conditionalUsages,
         };
     }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // DEBUGGING HELPERS
+    // These methods help understand what's happening during analysis.
+    // Use them when investigating why a path is missing or has the wrong type.
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Explains a path by tracing its equivalencies and showing where data comes from.
+     *
+     * @example
+     * ```typescript
+     * const explanation = sds.explainPath('MyComponent', 'user.id');
+     * console.log(explanation);
+     * // {
+     * //   path: 'user.id',
+     * //   scope: 'MyComponent',
+     * //   schemaValue: 'string',
+     * //   equivalencies: [
+     * //     { scope: 'MyComponent', path: 'signature[0].user.id' },
+     * //     { scope: 'UserProfile', path: 'props.user.id' }
+     * //   ],
+     * //   source: { scope: 'fetchUser', path: 'functionCallReturnValue(fetch).data.user.id' }
+     * // }
+     * ```
+     */
+    explainPath(scopeName, path) {
+        const scopeNode = this.getScopeOrFunctionCallInfo(scopeName);
+        if (!scopeNode) {
+            return {
+                path,
+                scope: scopeName,
+                schemaValue: undefined,
+                equivalencies: [],
+                databaseEntry: undefined,
+                source: undefined,
+            };
+        }
+        const schemaValue = scopeNode.schema?.[path];
+        const rawEquivalencies = scopeNode.equivalencies?.[path] ?? [];
+        const equivalencies = rawEquivalencies.map((eq) => ({
+            scope: eq.scopeNodeName,
+            path: eq.schemaPath,
+            reason: eq.equivalencyReason,
+        }));
+        const databaseEntry = this.getEquivalenciesDatabaseEntry(scopeName, path);
+        const source = databaseEntry?.sourceCandidates?.[0] &&
+            databaseEntry.sourceCandidates.length > 0
+            ? {
+                scope: databaseEntry.sourceCandidates[0].scopeNodeName,
+                path: databaseEntry.sourceCandidates[0].schemaPath,
+            }
+            : undefined;
+        return {
+            path,
+            scope: scopeName,
+            schemaValue,
+            equivalencies,
+            databaseEntry,
+            source,
+        };
+    }
+    /**
+     * Dumps the current state of analysis for inspection.
+     * Useful for understanding the overall state or finding issues.
+     *
+     * @param options - What to include in the dump
+     * @returns A summary object with requested data
+     */
+    dumpState(options) {
+        const includeSchemas = options?.includeSchemas ?? false;
+        const includeEquivalencies = options?.includeEquivalencies ?? false;
+        const scopeFilter = options?.scopeFilter;
+        const scopeNames = Object.keys(this.scopeNodes).filter((name) => !scopeFilter || name.includes(scopeFilter));
+        const scopes = scopeNames.map((name) => {
+            const node = this.scopeNodes[name];
+            const result = {
+                name,
+                schemaKeyCount: Object.keys(node.schema ?? {}).length,
+                equivalencyKeyCount: Object.keys(node.equivalencies ?? {}).length,
+                functionCallCount: node.functionCalls?.length ?? 0,
+            };
+            if (includeSchemas) {
+                result.schema = node.schema;
+            }
+            if (includeEquivalencies) {
+                result.equivalencies = Object.entries(node.equivalencies ?? {}).reduce((acc, [key, vals]) => {
+                    acc[key] = vals.map((v) => ({
+                        scope: v.scopeNodeName,
+                        path: v.schemaPath,
+                    }));
+                    return acc;
+                }, {});
+            }
+            return result;
+        });
+        return {
+            scopeCount: Object.keys(this.scopeNodes).length,
+            externalCallCount: this.externalFunctionCalls.length,
+            equivalencyDatabaseSize: this.equivalencyDatabase.length,
+            metrics: {
+                addToSchemaCallCount,
+                followEquivalenciesCallCount,
+                maxEquivalencyChainDepth,
+            },
+            scopes,
+        };
+    }
+    /**
+     * Traces the full equivalency chain for a path, showing how data flows.
+     * This is the most detailed debugging tool for understanding data tracing.
+     *
+     * @example
+     * ```typescript
+     * const chain = sds.traceEquivalencyChain('MyComponent', 'user.id');
+     * // Returns array of steps showing how user.id is traced back to its source
+     * ```
+     */
+    traceEquivalencyChain(scopeName, path, maxDepth = 20) {
+        const chain = [];
+        const visited = new Set();
+        const queue = [
+            { scope: scopeName, path, depth: 0 },
+        ];
+        while (queue.length > 0 && chain.length < maxDepth) {
+            const current = queue.shift();
+            const key = `${current.scope}::${current.path}`;
+            if (visited.has(key))
+                continue;
+            visited.add(key);
+            const scopeNode = this.getScopeOrFunctionCallInfo(current.scope);
+            const schemaValue = scopeNode?.schema?.[current.path];
+            const rawEquivalencies = scopeNode?.equivalencies?.[current.path] ?? [];
+            const nextEquivalencies = rawEquivalencies.map((eq) => ({
+                scope: eq.scopeNodeName,
+                path: eq.schemaPath,
+                reason: eq.equivalencyReason,
+            }));
+            chain.push({
+                step: chain.length + 1,
+                scope: current.scope,
+                path: current.path,
+                schemaValue,
+                nextEquivalencies,
+            });
+            // Add next equivalencies to queue for further tracing
+            for (const eq of nextEquivalencies) {
+                const nextKey = `${eq.scope}::${eq.path}`;
+                if (!visited.has(nextKey)) {
+                    queue.push({
+                        scope: eq.scope,
+                        path: eq.path,
+                        depth: current.depth + 1,
+                    });
+                }
+            }
+        }
+        return chain;
+    }
+    /**
+     * Finds all paths in a scope that match a pattern.
+     * Useful for finding related paths when debugging.
+     *
+     * @example
+     * ```typescript
+     * const paths = sds.findPaths('MyComponent', /user/);
+     * // Returns all schema paths containing "user"
+     * ```
+     */
+    findPaths(scopeName, pattern) {
+        const scopeNode = this.getScopeOrFunctionCallInfo(scopeName);
+        if (!scopeNode)
+            return [];
+        const regex = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+        const results = [];
+        // Search in schema
+        for (const [path, value] of Object.entries(scopeNode.schema ?? {})) {
+            if (regex.test(path)) {
+                results.push({
+                    path,
+                    value,
+                    hasEquivalencies: !!scopeNode.equivalencies?.[path]?.length,
+                });
+            }
+        }
+        // Also search equivalency keys that might not be in schema
+        for (const path of Object.keys(scopeNode.equivalencies ?? {})) {
+            if (regex.test(path) && !results.find((r) => r.path === path)) {
+                results.push({
+                    path,
+                    value: scopeNode.schema?.[path] ?? 'not-in-schema',
+                    hasEquivalencies: true,
+                });
+            }
+        }
+        return results.sort((a, b) => a.path.localeCompare(b.path));
+    }
+    /**
+     * Returns a summary of why a path might be missing from the schema.
+     * Checks common issues that cause paths to not appear.
+     */
+    diagnoseMissingPath(scopeName, path) {
+        const scopeNode = this.getScopeOrFunctionCallInfo(scopeName);
+        const possibleReasons = [];
+        const suggestions = [];
+        if (!scopeNode) {
+            possibleReasons.push(`Scope "${scopeName}" does not exist`);
+            suggestions.push(`Available scopes: ${Object.keys(this.scopeNodes).join(', ')}`);
+            return {
+                exists: false,
+                inSchema: false,
+                inEquivalencies: false,
+                possibleReasons,
+                suggestions,
+            };
+        }
+        const inSchema = path in (scopeNode.schema ?? {});
+        const inEquivalencies = path in (scopeNode.equivalencies ?? {});
+        if (inSchema) {
+            return {
+                exists: true,
+                inSchema: true,
+                inEquivalencies,
+                possibleReasons: [],
+                suggestions: [],
+            };
+        }
+        // Check for similar paths
+        const allPaths = [
+            ...Object.keys(scopeNode.schema ?? {}),
+            ...Object.keys(scopeNode.equivalencies ?? {}),
+        ];
+        const similarPaths = allPaths.filter((p) => {
+            const pathParts = path.split('.');
+            const pParts = p.split('.');
+            return (pathParts.some((part) => pParts.includes(part)) ||
+                p.includes(path) ||
+                path.includes(p));
+        });
+        if (similarPaths.length > 0) {
+            possibleReasons.push(`Path "${path}" not found but similar paths exist`);
+            suggestions.push(`Similar paths: ${similarPaths.slice(0, 5).join(', ')}`);
+        }
+        // Check if it's a partial path
+        const parentPath = path.split('.').slice(0, -1).join('.');
+        if (parentPath && scopeNode.schema?.[parentPath]) {
+            possibleReasons.push(`Parent path "${parentPath}" exists with value "${scopeNode.schema[parentPath]}"`);
+            suggestions.push(`The property might not have been accessed in the analyzed code`);
+        }
+        // Check visited tracker
+        const wasVisited = this.visitedTracker.wasVisited(scopeName, path);
+        if (wasVisited) {
+            possibleReasons.push(`Path was visited during analysis but not written`);
+            suggestions.push(`Check if the path was filtered by isValidPath() or hit cycle detection`);
+        }
+        if (possibleReasons.length === 0) {
+            possibleReasons.push(`Path "${path}" was never encountered during analysis`);
+            suggestions.push(`Verify the path is accessed in the source code being analyzed`);
+        }
+        return {
+            exists: false,
+            inSchema,
+            inEquivalencies,
+            possibleReasons,
+            suggestions,
+        };
+    }
+    /**
+     * Analyzes the stored equivalencies to provide aggregate statistics.
+     * Call this AFTER analysis completes to understand equivalency patterns.
+     *
+     * @example
+     * ```typescript
+     * const analysis = sds.analyzeEquivalencies();
+     * console.log(analysis.byReason); // Count by reason
+     * console.log(analysis.byScope);  // Count by scope
+     * console.log(analysis.hotSpots); // Scopes with most equivalencies
+     * ```
+     */
+    analyzeEquivalencies() {
+        const byReason = {};
+        const byScope = {};
+        let total = 0;
+        // Collect from all scope nodes
+        for (const scopeName of Object.keys(this.scopeNodes)) {
+            const scopeNode = this.scopeNodes[scopeName];
+            const equivalencies = scopeNode.equivalencies ?? {};
+            for (const path of Object.keys(equivalencies)) {
+                for (const eq of equivalencies[path]) {
+                    total++;
+                    const reason = eq.equivalencyReason ?? 'unknown';
+                    byReason[reason] = (byReason[reason] ?? 0) + 1;
+                    byScope[scopeName] = (byScope[scopeName] ?? 0) + 1;
+                }
+            }
+        }
+        // Also check external function calls
+        for (const fc of this.externalFunctionCalls) {
+            const equivalencies = fc.equivalencies ?? {};
+            for (const path of Object.keys(equivalencies)) {
+                for (const eq of equivalencies[path]) {
+                    total++;
+                    const reason = eq.equivalencyReason ?? 'unknown';
+                    byReason[reason] = (byReason[reason] ?? 0) + 1;
+                    byScope[fc.name] = (byScope[fc.name] ?? 0) + 1;
+                }
+            }
+        }
+        // Find hot spots (scopes with most equivalencies)
+        const hotSpots = Object.entries(byScope)
+            .map(([scope, count]) => ({ scope, count }))
+            .sort((a, b) => b.count - a.count)
+            .slice(0, 10);
+        // Find reasons that appear in stored equivalencies but aren't in ALLOWED list
+        const unusedReasons = Object.keys(byReason).filter((reason) => !ALLOWED_EQUIVALENCY_REASONS.has(reason));
+        return {
+            total,
+            byReason,
+            byScope,
+            hotSpots,
+            unusedReasons,
+        };
+    }
+    /**
+     * Validates equivalencies and identifies potential problems.
+     * Returns actionable issues that may indicate bugs or optimization opportunities.
+     *
+     * @example
+     * ```typescript
+     * const issues = sds.validateEquivalencies();
+     * if (issues.length > 0) {
+     *   console.log('Found issues:', issues);
+     * }
+     * ```
+     */
+    validateEquivalencies() {
+        const issues = [];
+        const allScopeNames = new Set([
+            ...Object.keys(this.scopeNodes),
+            ...this.externalFunctionCalls.map((fc) => fc.name),
+        ]);
+        // Check all scope nodes
+        for (const scopeName of Object.keys(this.scopeNodes)) {
+            const scopeNode = this.scopeNodes[scopeName];
+            const equivalencies = scopeNode.equivalencies ?? {};
+            for (const [path, eqs] of Object.entries(equivalencies)) {
+                for (const eq of eqs) {
+                    // Check 1: Does the target scope exist?
+                    if (!allScopeNames.has(eq.scopeNodeName)) {
+                        issues.push({
+                            type: 'broken_reference',
+                            severity: 'error',
+                            scope: scopeName,
+                            path,
+                            details: `Equivalency points to non-existent scope "${eq.scopeNodeName}"`,
+                        });
+                        continue;
+                    }
+                    // Check 2: Does the target path exist in target scope's schema or equivalencies?
+                    const targetScope = this.getScopeOrFunctionCallInfo(eq.scopeNodeName);
+                    if (targetScope) {
+                        const hasInSchema = eq.schemaPath in (targetScope.schema ?? {});
+                        const hasInEquivalencies = eq.schemaPath in (targetScope.equivalencies ?? {});
+                        // Only flag as dead end if it's a leaf path (no sub-properties exist)
+                        if (!hasInSchema && !hasInEquivalencies) {
+                            const hasSubPaths = Object.keys(targetScope.schema ?? {}).some((p) => p.startsWith(eq.schemaPath + '.') ||
+                                p.startsWith(eq.schemaPath + '['));
+                            if (!hasSubPaths) {
+                                issues.push({
+                                    type: 'dead_end',
+                                    severity: 'warning',
+                                    scope: scopeName,
+                                    path,
+                                    details: `Equivalency to "${eq.scopeNodeName}::${eq.schemaPath}" - path not in schema`,
+                                });
+                            }
+                        }
+                    }
+                }
+                // Check 3: Trace chain depth
+                const chain = this.traceEquivalencyChain(scopeName, path, 50);
+                if (chain.length >= 20) {
+                    issues.push({
+                        type: 'long_chain',
+                        severity: 'warning',
+                        scope: scopeName,
+                        path,
+                        details: `Equivalency chain depth is ${chain.length} (may impact performance)`,
+                    });
+                }
+                // Check for potential cycles (chain that returns to starting point)
+                const visited = new Set();
+                for (const step of chain) {
+                    const key = `${step.scope}::${step.path}`;
+                    if (visited.has(key)) {
+                        issues.push({
+                            type: 'circular',
+                            severity: 'warning',
+                            scope: scopeName,
+                            path,
+                            details: `Circular reference detected at ${key}`,
+                        });
+                        break;
+                    }
+                    visited.add(key);
+                }
+            }
+        }
+        return issues;
+    }
 }
 //# sourceMappingURL=ScopeDataStructure.js.map