@codeyam/codeyam-cli 0.0.0 → 0.1.0-staging.036391e

package/analyzer-template/packages/ai/src/lib/astScopes/astScopeAnalyzer.ts

@@ -0,0 +1,1092 @@
+import ts from 'typescript';
+import { StatementInfo } from '~codeyam/types';
+import {
+  AnalysisContext,
+  AnalysisIssue,
+  AstScopeAnalysisResult,
+  CompletenessInfo,
+  CompoundConditional,
+  ConditionalUsage,
+  DerivedVariableInfo,
+} from './types';
+import { PatternHandler } from './patterns/patternHandler';
+import { VariableDeclarationHandler } from './patterns/variableDeclarationHandler';
+import { FunctionDeclarationHandler } from './patterns/functionDeclarationHandler';
+import { ReturnStatementHandler } from './patterns/returnStatementHandler';
+import { IfStatementHandler } from './patterns/ifStatementHandler';
+import { BlockHandler } from './patterns/blockHandler';
+import { ForStatementHandler } from './patterns/forStatementHandler';
+import { ForInStatementHandler } from './patterns/forInStatementHandler';
+import { ForOfStatementHandler } from './patterns/forOfStatementHandler';
+import { WhileStatementHandler } from './patterns/whileStatementHandler';
+import { DoStatementHandler } from './patterns/doStatementHandler';
+import { SwitchStatementHandler } from './patterns/switchStatementHandler';
+import { TryStatementHandler } from './patterns/tryStatementHandler';
+import { BreakStatementHandler } from './patterns/breakStatementHandler';
+import { StandaloneExpressionHandler } from './patterns/standaloneExpressionHandler';
+import { TypeAndInterfaceHandler } from './patterns/typeAndInterfaceHandler';
+import { nodeToSource } from './nodeToSource';
+import { FileAnalyzer } from '~codeyam/analyze';
+import { StructuredPath } from './paths';
+import { processExpression } from './processExpression'; // Import the new function
+import { ThrowStatementHandler } from './patterns/throwStatementHandler';
+
+/**
+ * AST-based Scope Analyzer - Extracts variable type structures and equivalence mappings
+ * *
+ * KEY CHARACTERISTICS:
+ *
+ * 1. Pattern-first traversal (not a naive visitor pattern):
+ *    - Does NOT blindly traverse all nodes in the AST
+ *    - Each handler selectively processes only relevant nodes for its pattern
+ *    - Processing only occurs on explicitly registered patterns and node types
+ *
+ * 2. Deterministic analysis flag (isComplete): ⚠️ IMPORTANT
+ *    - Name "isComplete" can be misleading: it's NOT about implementation completeness
+ *    - True = "ALL information NEEDED for analysis CAN be extracted deterministically"
+ *    - False = "SOME information REQUIRES LLM assistance/inference"
+ *    - Critical decision point: when true, we can bypass LLM calls entirely
+ *    - Undefined variables (like 'x = y' where 'y' is undefined) don't affect completeness
+ *      as long as we can deterministically extract the necessary relationship
+ *    - References that can be fully mapped (whether their targets exist or not) are "complete"
+ *    - Simple patterns (assignments, function params, property access) are typically "complete"
+ *
+ * 3. Accuracy vs. completeness (isFullySupported vs. isComplete):
+ *    - isFullySupported = "Did our implementation handle everything it encountered?"
+ *    - isComplete = "Can all necessary information be extracted without guesswork?"
+ *    - Example: For 'const x = complexExpression()', we may handle it (supported)
+ *      but still need LLM to infer types (incomplete)
+ *
+ * 4. Non-blocking vs. blocking issues:
+ *    - Non-blocking: Pattern recognized but partial information extracted
+ *    - Blocking: Pattern fundamentally cannot be processed by current implementation
+ *    - Both cause isComplete to be false, but handling differs downstream
+ *
+ * 5. Handler registration order matters:
+ *    - First matching handler gets priority (StandaloneExpressionHandler is first)
+ *    - No cascading/fallthrough between handlers
+ *
+ * 6. Selective child traversal:
+ *    - Only specific node types trigger child traversal
+ *    - Other node types don't automatically traverse children
+ *
+ * 7. PATH NOTATION REFERENCE:
+ *    - Standard property:        "obj.prop.subprop"
+ *    - Array indexing:           "arr[0]", "arr[index]"
+ *    - Array elements:           "arr[]" (any element)
+ *    - Dynamic properties:       "obj[key]" (access by variable)
+ *    - Object keys:              "obj*key*" (for-in loop key)
+ *    - Function parameters:      "functionName().signature[0]"
+ *    - Function return values:   "functionName().functionCallReturnValue"
+ *    - Return statements:        "returnValue" (special keyword)
+ *
+ * 8. SPECIAL FUNCTION HANDLING:
+ *    - React useState:           "count": "setCount().signature[0]"
+ *    - Array methods:
+ *      • map(): "returnValue[]": "cyScope1()"
+ *      • filter(): Preserves item structure
+ *      • find(): "returnValue": "items[]"
+ *      • reduce(): "result": "cyScope1()"
+ *    - JSX components:           "Component().signature[0].propName"
+ *    - Method chaining:          Each method tracked in full path
+ *
+ * This analyzer serves as the first phase in the scope analysis pipeline, potentially
+ * bypassing LLM calls when deterministic analysis is sufficient. The isComplete flag
+ * is the critical decision point for whether we can skip LLM processing entirely.
+ *
+ * FUNCTION RETURN VALUE HANDLING:
+ *    * When one or more function calls appear on the RIGHT side of an equivalence mapping,
+ *      the *last* one gets `.functionCallReturnValue` appended
+ *    * We never append `.functionCallReturnValue` on the LEFT side ofeither the structure
+ *      or equivalentVariables maps
+ */
+export class ASTScopeAnalyzer {
+  private structure: Record<string, string> = {};
+  private equivalentVariables: Record<string, string | string[]> = {};
+  private environmentVariables: string[] = [];
+  private conditionalUsages: Record<string, ConditionalUsage[]> = {};
+  private compoundConditionals: CompoundConditional[] = [];
+  private conditionalEffects: import('./types').ConditionalEffect[] = [];
+  private childBoundaryGatingConditions: Record<string, ConditionalUsage[]> =
+    {};
+  private jsxRenderingUsages: import('./types').JsxRenderingUsage[] = [];
+  /**
+   * Tracks derived boolean variables and their source expressions.
+   * Maps variable name to derivation info.
+   * Example: { hasAnalysis: { sourcePath: 'analysis', operation: 'notNull' } }
+   */
+  private derivedVariables: Record<string, DerivedVariableInfo> = {};
+  private sourceFile: ts.SourceFile;
+  private statementInfo: StatementInfo;
+  private issues: AnalysisIssue[] = [];
+  private patternHandlers: PatternHandler[] = [];
+  private fileAnalyzer: FileAnalyzer;
+
+  constructor(fileAnalyzer: FileAnalyzer, statementInfo: StatementInfo) {
+    this.statementInfo = statementInfo;
+
+    this.fileAnalyzer = fileAnalyzer;
+    this.sourceFile = fileAnalyzer.sourceFile;
+
+    // Register pattern handlers
+    this.registerPatternHandlers();
+  }
+
+  /**
+   * Register all pattern handlers
+   *
+   * IMPORTANT: Registration order matters! More specialized handlers should be registered first,
+   * and general catch-all handlers should be registered last. This ensures that specialized
+   * handlers get first opportunity to process nodes they're designed for.
+   */
+  private registerPatternHandlers(): void {
+    // Register specialized handlers first
+
+    this.patternHandlers.push(new VariableDeclarationHandler());
+    this.patternHandlers.push(new FunctionDeclarationHandler());
+    this.patternHandlers.push(new ReturnStatementHandler());
+
+    // Control flow statement handlers
+    this.patternHandlers.push(new IfStatementHandler());
+    this.patternHandlers.push(new BlockHandler());
+    this.patternHandlers.push(new ForStatementHandler());
+    this.patternHandlers.push(new ForInStatementHandler());
+    this.patternHandlers.push(new ForOfStatementHandler());
+    this.patternHandlers.push(new WhileStatementHandler());
+    this.patternHandlers.push(new DoStatementHandler());
+    this.patternHandlers.push(new SwitchStatementHandler());
+    this.patternHandlers.push(new TryStatementHandler());
+    this.patternHandlers.push(new ThrowStatementHandler());
+    this.patternHandlers.push(new BreakStatementHandler());
+    this.patternHandlers.push(new TypeAndInterfaceHandler());
+
+    // Add the general-purpose handler last
+    this.patternHandlers.push(new StandaloneExpressionHandler());
+  }
+
+  /**
+   * Performs the analysis by identifying and processing patterns in the AST
+   */
+  analyze(): AstScopeAnalysisResult {
+    // Create analysis context
+    const context: AnalysisContext = this.createAnalysisContext();
+
+    // Process the AST with a pattern-first approach
+    const relevantNodes = this.getNodesWithinRange(
+      this.sourceFile,
+      this.statementInfo.start,
+      this.statementInfo.end,
+    );
+
+    this.processNodes(relevantNodes, context);
+
+    // Calculate completeness
+    const completeness = this.calculateCompleteness();
+
+    // Debug log the results
+    // console.log(
+    //   'Analysis results:',
+    //   JSON.stringify(
+    //     {
+    //       structure: this.structure,
+    //       equivalentVariables: this.equivalentVariables,
+    //       isComplete:
+    //         completeness.equivalences === 'full' &&
+    //         completeness.structures === 'full',
+    //       completeness,
+    //     },
+    //     null,
+    //     2,
+    //   ),
+    // );
+
+    // Debug log the issues
+    // console.log(
+    //   'Issues:',
+    //   this.issues.map((issue) => ({
+    //     nodeKind: ts.SyntaxKind[issue.nodeKind],
+    //     category: issue.category,
+    //     severity: issue.severity,
+    //     message: issue.message,
+    //   })),
+    // );
+
+    return {
+      structure: this.structure,
+      equivalentVariables: this.equivalentVariables,
+      environmentVariables: this.environmentVariables,
+      conditionalUsages: this.conditionalUsages,
+      compoundConditionals: this.compoundConditionals,
+      conditionalEffects: this.conditionalEffects,
+      derivedVariables: this.derivedVariables,
+      childBoundaryGatingConditions: this.childBoundaryGatingConditions,
+      jsxRenderingUsages: this.jsxRenderingUsages,
+      isComplete:
+        completeness.equivalences === 'full' &&
+        completeness.structures === 'full',
+      completeness,
+    };
+  }
+
+  private createAnalysisContext(): AnalysisContext {
+    const context: AnalysisContext = {
+      sourceFile: this.sourceFile,
+      statementInfo: this.statementInfo,
+      typeChecker: this.fileAnalyzer.typeChecker,
+      addEquivalence: (leftSide, rightSide) =>
+        this.addEquivalence(leftSide, rightSide),
+      addMultipleEquivalencies: (leftSide, rightSides) =>
+        this.addMultipleEquivalencies(leftSide, rightSides),
+      addType: (path, type) => this.addType(path, type),
+      addEnvironmentVariable: (variablePath) =>
+        this.addEnvironmentVariable(variablePath),
+      markUnsupported: (node, message, isBlocking) =>
+        this.markUnsupported(node, message, isBlocking),
+      markSemanticLimitation: (node, message) =>
+        this.markSemanticLimitation(node, message),
+      getStructuralPath: (node) => this.getStructuralPath(node, context),
+      inferAndAddType: (path, node) => this.inferAndAddType(path, node),
+      processNode: (node) => this.processNode(node, context),
+      getTypeInfo: (path) => this.structure[path.toString()],
+      inferTypeFromNode: (node) => this.inferTypeFromNode(node),
+      inferTypeFromTsType: (tsType) => this.inferTypeFromTsType(tsType),
+      getStructure: () => this.structure,
+      getEquivalentVariables: () => this.equivalentVariables,
+      getChildBoundary: (node) => this.getChildBoundary(node, context),
+      isChildBoundary: (node) => this.isChildBoundary(node, context),
+      addChildBoundaryEquivalence: (equivalence, node) =>
+        this.addChildBoundaryEquivalence(equivalence, node, context),
+      artificialReturnStatementProcessed: false,
+      setArtificialReturnStatementProcessed: () =>
+        this.setArtificialReturnStatementProcessed(context),
+      isArtificialReturnStatement: (node) =>
+        this.isArtificialReturnStatement(node, context),
+      processExpression: (node, targetPath) =>
+        processExpression({ node, context, targetPath }),
+      addConditionalUsage: (usage) => this.addConditionalUsage(usage),
+      getConditionalUsages: () => this.conditionalUsages,
+      addChildBoundaryGatingCondition: (childName, condition) =>
+        this.addChildBoundaryGatingCondition(childName, condition),
+      getChildBoundaryGatingConditions: () =>
+        this.childBoundaryGatingConditions,
+      addDerivedVariable: (variableName, derivationInfo) =>
+        this.addDerivedVariable(variableName, derivationInfo),
+      addCompoundConditional: (compound) =>
+        this.addCompoundConditional(compound),
+      getCompoundConditionals: () => this.compoundConditionals,
+      updateSchemaType: (path, newType) => this.updateSchemaType(path, newType),
+      addConditionalEffect: (effect) => this.addConditionalEffect(effect),
+      getConditionalEffects: () => this.conditionalEffects,
+      addJsxRenderingUsage: (usage) => this.addJsxRenderingUsage(usage),
+      getJsxRenderingUsages: () => this.jsxRenderingUsages,
+    };
+    return context;
+  }
+
+  private getNodeRange(
+    node: ts.Node,
+    sourceFile: ts.SourceFile,
+  ): { nodeStart: number; nodeEnd: number } {
+    // Use getStart(sourceFile) to get the position after leading trivia.
+    // Note: We intentionally don't adjust for leadingContentOffset here because
+    // the positions from isolateStatements are calculated using getStart() too,
+    // which uses the same sourceFile.text coordinate system.
+    return {
+      nodeStart: node.getStart(sourceFile),
+      nodeEnd: node.getEnd(),
+    };
+  }
+
+  private getNodesWithinRange(
+    sourceFile: ts.SourceFile,
+    rangeStart: number,
+    rangeEnd: number,
+  ): ts.Node[] {
+    const nodes: ts.Node[] = [];
+
+    const getNodeRange = this.getNodeRange;
+    function visit(node: ts.Node) {
+      const { nodeStart, nodeEnd } = getNodeRange(node, sourceFile);
+
+      if (nodeStart >= rangeStart && nodeEnd <= rangeEnd + 1) {
+        if (node.getText().length > 0) {
+          nodes.push(node);
+        }
+        return; // Stop recursing into this node's children.
+      }
+
+      // Otherwise, keep checking its children.
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return nodes;
+  }
+
+  /**
+   * Process a node by finding and applying the appropriate pattern handlers
+   */
+  private processNode(node: ts.Node, context: AnalysisContext) {
+    if (context.isChildBoundary(node)) {
+      // console.info("SKIPPING:\n\n", node.getText(context.sourceFile));
+      return;
+    }
+
+    // Skip EmptyStatement (`;`) - it has no semantic meaning
+    if (ts.isEmptyStatement(node)) {
+      return;
+    }
+
+    // if (
+    //   ts.isJsxOpeningElement(node) ||
+    //   ts.isJsxText(node) ||
+    //   ts.isJsxClosingElement(node) ||
+    //   ts.isJsxExpression(node) ||
+    //   ts.isJsxSelfClosingElement(node)
+    // ) {
+    //   console.warn(
+    //     `Saw JSX node: ${ts.SyntaxKind[node.kind]} with ts.isExpression(node) = ${ts.isExpression(node)}`,
+    //   );
+    // }
+
+    let handled = false;
+    for (const handler of this.patternHandlers) {
+      if (handler.canHandle(node, context)) {
+        handled = true;
+        handler.process(node, context);
+      }
+    }
+    if (!handled) {
+      handled = true;
+      if (ts.isSourceFile(node) || ts.isBlock(node)) {
+        // For source files and blocks, process all statements
+        node.statements.forEach((statement) => {
+          this.processNode(statement, context);
+        });
+      } else if (ts.isVariableStatement(node)) {
+        // For variable statements, process each declaration
+        node.declarationList.declarations.forEach((declaration) => {
+          this.processNode(declaration, context);
+        });
+      } else {
+        handled = false;
+      }
+    }
+
+    if (!handled) {
+      if (this.isStatementOrDeclaration(node)) {
+        // console.warn(
+        //   `No handler found for node kind: ${ts.SyntaxKind[node.kind]}`,
+        //   node.getText(context.sourceFile),
+        //   new Error().stack,
+        // );
+        this.markUnsupported(
+          node,
+          `No handler found for node kind: ${ts.SyntaxKind[node.kind]}`,
+          false, // Non-blocking
+        );
+      } else {
+        // TODO: this should ideally not be necessary!
+        // console.warn(
+        //   `Completely unexpected node kind: ${node.kind} => ${ts.SyntaxKind[node.kind]}`,
+        //   node.getText(context.sourceFile),
+        //   new Error().stack,
+        // );
+      }
+    }
+  }
+
+  private processNodes(nodes: ts.Node[], context: AnalysisContext) {
+    // for (let node of nodes) {
+    //   console.warn(
+    //     `Top level processNodes: ${ts.SyntaxKind[node.kind]} = ${node.getText()}`,
+    //     {
+    //       isChildBoundary: this.isChildBoundary(node, context),
+    //     },
+    //   );
+    // }
+    for (const node of nodes) {
+      this.processNode(node, context);
+    }
+  }
+
+  private getChildBoundary(node: ts.Node, context: AnalysisContext) {
+    return context.statementInfo.childBoundaries.find((childBoundary) => {
+      return (
+        node.getStart(context.sourceFile) >= childBoundary.start &&
+        node.getEnd() <= childBoundary.end + 1 // accounting for optional ";"
+      );
+    });
+  }
+
+  private isChildBoundary(node: ts.Node, context: AnalysisContext): boolean {
+    return !!context.getChildBoundary(node);
+  }
+
+  private addChildBoundaryEquivalence(
+    equivalence: StructuredPath,
+    node: ts.Node,
+    context: AnalysisContext,
+  ) {
+    const childBoundary = context.getChildBoundary(node);
+    if (childBoundary) {
+      let childBoundaryName = childBoundary.name;
+      if (childBoundaryName) {
+        // TODO: This is frustrating. Would be nice to improve how this is tracked.
+        if (context.statementInfo.text.includes(childBoundaryName + 'F')) {
+          childBoundaryName = childBoundaryName + 'F';
+        } else if (
+          context.statementInfo.text.includes(childBoundaryName + '()')
+        ) {
+          childBoundaryName = childBoundaryName + '()';
+        }
+
+        const childBoundaryPath = StructuredPath.fromBase(childBoundaryName);
+
+        context.addEquivalence(equivalence, childBoundaryPath);
+        context.addType(equivalence, 'unknown');
+        context.addType(childBoundaryPath, 'unknown');
+      }
+    }
+  }
+
+  private setArtificialReturnStatementProcessed(context: AnalysisContext) {
+    context.artificialReturnStatementProcessed = true;
+  }
+
+  private isArtificialReturnStatement(
+    node: ts.Node,
+    context: AnalysisContext,
+  ): boolean {
+    if (context.artificialReturnStatementProcessed) return false;
+    if (ts.isReturnStatement(node)) return false;
+    if (node.getText(context.sourceFile).startsWith('return')) return false;
+    if (!context.statementInfo.text.startsWith('return')) return false;
+    if (context.statementInfo.start !== node.getStart(context.sourceFile))
+      if (ts.isReturnStatement(node)) return false;
+    if (node.getText(context.sourceFile).startsWith('return')) return false;
+    if (!context.statementInfo.text.startsWith('return')) return false;
+    if (context.statementInfo.start !== node.getStart(context.sourceFile))
+      return false;
+    if (context.statementInfo.end !== node.getEnd()) return false;
+    return true;
+  }
+
+  /**
+   * Check if a node is a statement or declaration (i.e., a high-level construct)
+   */
+  private isStatementOrDeclaration(node: ts.Node): boolean {
+    return (
+      ts.isStatement(node) ||
+      ts.isFunctionDeclaration(node) ||
+      ts.isClassDeclaration(node) ||
+      ts.isInterfaceDeclaration(node) ||
+      ts.isTypeAliasDeclaration(node) ||
+      ts.isEnumDeclaration(node) ||
+      ts.isVariableDeclaration(node) ||
+      ts.isExpression(node)
+    );
+  }
+
+  /**
+   * Calculate detailed completeness information
+   *
+   * This determines whether all necessary information can be extracted deterministically
+   * without requiring LLM assistance (isComplete = true) or if some aspects need
+   * inference or guesswork (isComplete = false).
+   *
+   * Completeness is NOT about whether our implementation handled everything
+   * successfully - it's about whether we can bypass the LLM for this analysis.
+   * Simple patterns with references to undefined variables can still be "complete"
+   * if we can deterministically extract the relationship/structure.
+   */
+  private calculateCompleteness(): CompletenessInfo {
+    // Check if there are any blocking issues
+    const hasBlockingIssues = this.issues.some(
+      (issue) => issue.severity === 'blocking',
+    );
+
+    // Check if there are any non-blocking issues
+    const hasNonBlockingIssues = this.issues.some(
+      (issue) => issue.severity === 'non-blocking',
+    );
+
+    // Check specifically for semantic limitations
+    const hasSemanticLimitations = this.issues.some(
+      (issue) => issue.category === 'semantic-limitation',
+    );
+
+    // If we have semantic limitations, we consider the analysis incomplete
+    // even if we've successfully processed all syntax
+    return {
+      // Equivalence completeness
+      equivalences: hasBlockingIssues
+        ? 'invalid'
+        : hasNonBlockingIssues || hasSemanticLimitations
+          ? 'partial'
+          : 'full',
+
+      // Structure completeness
+      structures: hasBlockingIssues
+        ? 'invalid'
+        : hasNonBlockingIssues || hasSemanticLimitations
+          ? 'partial'
+          : 'full',
+
+      // Issues
+      issues: this.issues,
+    };
+  }
+
+  /**
+   * Mark a node as unsupported
+   */
+  private markUnsupported(
+    node: ts.Node,
+    message: string,
+    isBlocking: boolean,
+  ): void {
+    this.issues.push({
+      nodeKind: node.kind,
+      nodeText: node.getText(this.sourceFile),
+      category: 'unsupported-node',
+      severity: isBlocking ? 'blocking' : 'non-blocking',
+      message,
+    });
+  }
+
+  /**
+   * Mark a semantic limitation (pattern is syntactically supported but semantically not fully understood)
+   */
+  private markSemanticLimitation(node: ts.Node, message: string): void {
+    this.issues.push({
+      nodeKind: node.kind,
+      nodeText: node.getText(this.sourceFile),
+      category: 'semantic-limitation',
+      severity: 'non-blocking',
+      message,
+    });
+  }
+
+  /**
+   * Gets a structured representation of an expression's path
+   *
+   * Returns paths only for expressions that represent structural elements
+   * (variables, properties, etc.), not literal values.
+   *
+   * This filters out literals since they don't represent useful structural
+   * paths in the code and would just add noise to the structure.
+   *
+   * NOTE: This method now returns StructuredPath objects directly instead of
+   * converting them to strings, as part of our path representation migration.
+   *
+   * @param node The expression to get a path for
+   * @param context The analysis context
+   */
+  private getStructuralPath(
+    node: ts.Expression,
+    context: AnalysisContext,
+  ): StructuredPath | null {
+    return (
+      StructuredPath.fromNode(node, this.sourceFile) ??
+      nodeToSource(node, this.sourceFile)
+    );
+  }
+
+  /**
+   * Adds an equivalence relationship between two variable paths.
+   * Uses overwrite semantics - if an equivalence already exists, the new value replaces it
+   * (unless the new value is 'undefined' or 'null').
+   */
+  private addEquivalence(
+    leftSide: StructuredPath,
+    rightSide: StructuredPath,
+  ): void {
+    // Skip adding equivalences if left side is a literal path.
+    if (leftSide?.isLiteral()) {
+      return;
+    }
+
+    const leftSideStr = leftSide?.toLeftHandSideString();
+    const rightSideStr = rightSide?.toRightHandSideString();
+
+    if (leftSideStr && rightSideStr && leftSideStr !== rightSideStr) {
+      const existingValue = this.equivalentVariables[leftSideStr];
+      // Don't overwrite a meaningful value with 'undefined' or 'null'.
+      // This is critical for ternary conditionals like `const x = cond ? func() : undefined`
+      // or `const x = items.find(...) || null` where we want to preserve
+      // the equivalency to the more meaningful value (func()'s return value, items[]).
+      if (
+        existingValue &&
+        (rightSideStr === 'undefined' || rightSideStr === 'null')
+      ) {
+        return;
+      }
+      this.equivalentVariables[leftSideStr] = rightSideStr;
+    }
+  }
+
+  /**
+   * Adds multiple equivalence relationships for a single variable path.
+   * Used for OR expressions like `x = a || b` where x is equivalent to both a and b.
+   * The values are stored as an array to track all possible sources.
+   */
+  private addMultipleEquivalencies(
+    leftSide: StructuredPath,
+    rightSides: StructuredPath[],
+  ): void {
+    if (leftSide?.isLiteral()) {
+      return;
+    }
+
+    const leftSideStr = leftSide?.toLeftHandSideString();
+    if (!leftSideStr) return;
+
+    // Filter out invalid paths and convert to strings
+    const validRightSides = rightSides
+      .map((r) => r?.toRightHandSideString())
+      .filter((r): r is string => !!r && r !== leftSideStr);
+
+    // Remove duplicates while preserving order
+    const uniqueRightSides = [...new Set(validRightSides)];
+
+    // Filter out 'undefined' and 'null' unless they're the only values
+    const meaningfulValues = uniqueRightSides.filter(
+      (v) => v !== 'undefined' && v !== 'null',
+    );
+    const finalValues =
+      meaningfulValues.length > 0 ? meaningfulValues : uniqueRightSides;
+
+    if (finalValues.length === 0) return;
+
+    // Store as single value if only one, otherwise as array
+    this.equivalentVariables[leftSideStr] =
+      finalValues.length === 1 ? finalValues[0] : finalValues;
+  }
+
+  /**
+   * Adds a type for a variable path
+   */
+  private addType(path: string | StructuredPath, type: string): void {
+    if (path instanceof StructuredPath && path.isLiteral()) {
+      return;
+    }
+
+    const pathStr = path.toString();
+
+    // Do not overwrite a more specific type with a less specific one
+    if (
+      this.structure[pathStr] &&
+      this.structure[pathStr] !== 'unknown' &&
+      type === 'unknown'
+    )
+      return;
+    this.structure[pathStr] = type;
+  }
+
+  private addEnvironmentVariable(variablePath: string): void {
+    // Only add if not already present
+    if (!this.environmentVariables.includes(variablePath)) {
+      this.environmentVariables.push(variablePath);
+    }
+  }
+
+  /**
+   * Record a derived variable and its source expression.
+   * Called when we see patterns like:
+   * - const hasAnalysis = analysis !== null
+   * - const isLoading = status === 'loading'
+   * - const isBusy = isRunning || isQueued
+   */
+  private addDerivedVariable(
+    variableName: string,
+    derivationInfo: DerivedVariableInfo,
+  ): void {
+    this.derivedVariables[variableName] = derivationInfo;
+  }
+
+  /**
+   * Get derivation info for a variable if it was derived from another expression.
+   */
+  private getDerivedVariableInfo(
+    variableName: string,
+  ): DerivedVariableInfo | undefined {
+    return this.derivedVariables[variableName];
+  }
+
+  /**
+   * Add a conditional usage for key attribute detection
+   * Groups usages by path for easy lookup.
+   * Also enriches the usage with derivation info if the variable is derived.
+   */
+  private addConditionalUsage(usage: ConditionalUsage): void {
+    // Note: Derivation info enrichment now happens in analyzeScope.ts after all
+    // statements are processed, so derived variables from earlier statements can
+    // be used to enrich usages from later statements.
+
+    if (!this.conditionalUsages[usage.path]) {
+      this.conditionalUsages[usage.path] = [];
+    }
+    // Avoid duplicates with same location and conditionType
+    const exists = this.conditionalUsages[usage.path].some(
+      (existing) =>
+        existing.location === usage.location &&
+        existing.conditionType === usage.conditionType &&
+        JSON.stringify(existing.comparedValues) ===
+          JSON.stringify(usage.comparedValues),
+    );
+    if (!exists) {
+      this.conditionalUsages[usage.path].push(usage);
+    }
+  }
+
+  /**
+   * Add a gating condition for a child component.
+   * Called when we see patterns like: {hasAnalysis && <ChildComponent />}
+   * Groups conditions by child component name.
+   */
+  private addChildBoundaryGatingCondition(
+    childComponentName: string,
+    gatingCondition: ConditionalUsage,
+  ): void {
+    if (!this.childBoundaryGatingConditions[childComponentName]) {
+      this.childBoundaryGatingConditions[childComponentName] = [];
+    }
+    // Avoid duplicates with same path and conditionType
+    const exists = this.childBoundaryGatingConditions[childComponentName].some(
+      (existing) =>
+        existing.path === gatingCondition.path &&
+        existing.conditionType === gatingCondition.conditionType &&
+        existing.isNegated === gatingCondition.isNegated,
+    );
+    if (!exists) {
+      this.childBoundaryGatingConditions[childComponentName].push(
+        gatingCondition,
+      );
+    }
+  }
+
+  /**
+   * Add a compound conditional for key attribute dependency detection
+   */
+  private addCompoundConditional(compound: CompoundConditional): void {
+    // Avoid duplicates by expression and location (chainId is generated each time)
+    const exists = this.compoundConditionals.some(
+      (existing) =>
+        existing.expression === compound.expression &&
+        existing.sourceLocation.lineNumber ===
+          compound.sourceLocation.lineNumber,
+    );
+    if (!exists) {
+      this.compoundConditionals.push(compound);
+    }
+  }
+
+  /**
+   * Add a conditional effect (setter call inside a conditional)
+   */
+  private addConditionalEffect(
+    effect: import('./types').ConditionalEffect,
+  ): void {
+    this.conditionalEffects.push(effect);
+  }
+
+  /**
+   * Add a JSX rendering usage (array.map() or text interpolation)
+   * Deduplicates by path and rendering type
+   */
+  private addJsxRenderingUsage(
+    usage: import('./types').JsxRenderingUsage,
+  ): void {
+    // Deduplicate: don't add if we already have the same path + renderingType
+    const exists = this.jsxRenderingUsages.some(
+      (u) => u.path === usage.path && u.renderingType === usage.renderingType,
+    );
+    if (!exists) {
+      this.jsxRenderingUsages.push(usage);
+    }
+  }
+
+  /**
+   * Updates the schema type for a path, typically used when switch statements
+   * reveal the valid values for a parameter (creating a union type like "'a' | 'b' | 'c'")
+   *
+   * This method:
+   * 1. Updates the type for the given path
+   * 2. Also updates the type for any equivalent path (e.g., if "state" -> "signature[0]",
+   *    we update both "state" and "signature[0]")
+   * 3. For property paths like "data.status", if "data" -> "signature[0]",
+   *    we also update "signature[0].status"
+   */
+  private updateSchemaType(
+    path: string | StructuredPath,
+    newType: string,
+  ): void {
+    const pathStr = path.toString();
+
+    // Update the type for the given path
+    this.structure[pathStr] = newType;
+
+    // Also update the type for any equivalent path(s)
+    // e.g., if "state" -> "signature[0]", update "signature[0]" as well
+    const rawEquivalentPath = this.equivalentVariables[pathStr];
+    const equivalentPaths = Array.isArray(rawEquivalentPath)
+      ? rawEquivalentPath
+      : rawEquivalentPath
+        ? [rawEquivalentPath]
+        : [];
+    for (const equivalentPath of equivalentPaths) {
+      if (typeof equivalentPath === 'string') {
+        this.structure[equivalentPath] = newType;
+      }
+    }
+
+    // For property paths like "data.status", check if the base has an equivalence
+    // e.g., if "data" -> "signature[0]", transform "data.status" to "signature[0].status"
+    for (const [varPath, rawEquivalence] of Object.entries(
+      this.equivalentVariables,
+    )) {
+      if (pathStr.startsWith(varPath + '.')) {
+        const equivalences = Array.isArray(rawEquivalence)
+          ? rawEquivalence
+          : rawEquivalence
+            ? [rawEquivalence]
+            : [];
+        const suffix = pathStr.slice(varPath.length);
+        for (const equivalence of equivalences) {
+          if (typeof equivalence === 'string') {
+            const transformedPath = equivalence + suffix;
+            this.structure[transformedPath] = newType;
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Get a simplified type string from a TypeScript Type object
+   * This converts TypeScript's internal type representation to our type system
+   */
+  private inferTypeFromTsType(tsType: ts.Type): string {
+    // Handle primitive types
+    if (tsType.symbol?.getName() === 'Date') return 'date';
+    if (tsType.flags & ts.TypeFlags.String) return 'string';
+    if (tsType.flags & ts.TypeFlags.StringLiteral) return 'string';
+    if (tsType.flags & ts.TypeFlags.Number) return 'number';
+    if (tsType.flags & ts.TypeFlags.NumberLiteral) return 'number';
+    if (tsType.flags & ts.TypeFlags.Boolean) return 'boolean';
+    if (tsType.flags & ts.TypeFlags.BooleanLiteral) return 'boolean';
+    if (tsType.flags & ts.TypeFlags.Undefined) return 'undefined';
+    if (tsType.flags & ts.TypeFlags.Null) return 'null';
+    if (tsType.flags & ts.TypeFlags.Void) return 'void';
+
+    // Handle array type
+    if (tsType.flags & ts.TypeFlags.Object) {
+      const objectType = tsType as ts.ObjectType;
+
+      // Check for arrays
+      if (
+        objectType.objectFlags & ts.ObjectFlags.Reference &&
+        objectType.symbol &&
+        objectType.symbol.name === 'Array'
+      ) {
+        return 'array';
+      }
+
+      // Check for other common built-in types
+      if (objectType.symbol) {
+        const typeName = objectType.symbol.name.toLowerCase();
+        if (typeName === 'date') return 'date';
+        if (typeName === 'map') return 'map';
+        if (typeName === 'set') return 'set';
+        if (typeName === 'promise') return 'promise';
+      }
+
+      return 'unknown';
+    }
+
+    // Handle union types - we simplify unions to the most specific common type
+    if (tsType.flags & ts.TypeFlags.Union) {
+      const unionType = tsType as ts.UnionType;
+
+      // Check if it's a string literal union
+      const isAllStringLiterals = unionType.types.every(
+        (t) => (t.flags & ts.TypeFlags.StringLiteral) !== 0,
+      );
+      if (isAllStringLiterals) return 'string';
+
+      // Check if it's a number literal union
+      const isAllNumberLiterals = unionType.types.every(
+        (t) => (t.flags & ts.TypeFlags.NumberLiteral) !== 0,
+      );
+      if (isAllNumberLiterals) return 'number';
+
+      // Handle unions with null/undefined - this is important for useState patterns
+      // Extract all types in the union
+      const types = unionType.types.map((t) => this.inferTypeFromTsType(t));
+      const uniqueTypes = [...new Set(types)];
+
+      // Check if union includes null or undefined
+      const hasNull = uniqueTypes.includes('null');
+      const hasUndefined = uniqueTypes.includes('undefined');
+      const nonNullableTypes = uniqueTypes.filter(
+        (t) => t !== 'null' && t !== 'undefined',
+      );
+
+      // If we have exactly one non-nullable type + null/undefined, create union string
+      if ((hasNull || hasUndefined) && nonNullableTypes.length === 1) {
+        const baseType = nonNullableTypes[0];
+        const nullablePart = [hasNull && 'null', hasUndefined && 'undefined']
+          .filter(Boolean)
+          .join(' | ');
+        return `${baseType} | ${nullablePart}`;
+      }
+
+      // For other mixed unions, return 'unknown'
+      return 'unknown';
+    }
+
+    // Default to unknown for any other type
+    return 'unknown';
+  }
+
+  /**
+   * Infer type from a node using TypeScript's TypeChecker
+   */
+  private inferTypeFromNode(node: ts.Node): string {
+    if (!ts.isExpression(node)) {
+      return 'unknown';
+    }
+    try {
+      // Handle common literal cases directly for better reliability
+      if (ts.isNumericLiteral(node)) {
+        return 'number';
+      }
+      if (node.kind === ts.SyntaxKind.NullKeyword) {
+        return 'null';
+      }
+      if (
+        ts.isStringLiteral(node) ||
+        ts.isNoSubstitutionTemplateLiteral(node) ||
+        ts.isTemplateExpression(node)
+      ) {
+        return 'string';
+      }
+      if (
+        node.kind === ts.SyntaxKind.TrueKeyword ||
+        node.kind === ts.SyntaxKind.FalseKeyword
+      ) {
+        return 'boolean';
+      }
+      if (ts.isFunctionLike(node)) {
+        return 'function';
+      }
+      if (ts.isClassDeclaration(node) || ts.isClassExpression(node)) {
+        return 'class';
+      }
+
+      // Check if this identifier refers to a class
+      if (ts.isIdentifier(node)) {
+        try {
+          const symbol =
+            this.fileAnalyzer.typeChecker.getSymbolAtLocation(node);
+          if (symbol && symbol.declarations && symbol.declarations.length > 0) {
+            const declaration = symbol.declarations[0];
+            if (
+              ts.isClassDeclaration(declaration) ||
+              ts.isClassExpression(declaration)
+            ) {
+              return 'class';
+            }
+            if (
+              ts.isFunctionDeclaration(declaration) ||
+              ts.isFunctionExpression(declaration) ||
+              ts.isArrowFunction(declaration)
+            ) {
+              return 'function';
+            }
+          }
+        } catch (e) {
+          // If symbol lookup fails, continue with other checks
+        }
+      }
+
+      if (ts.isArrayLiteralExpression(node)) {
+        return 'array';
+      }
+      if (ts.isObjectLiteralExpression(node)) {
+        return 'object';
+      }
+      if (ts.isConditionalExpression(node)) {
+        const trueType = this.inferTypeFromNode(node.whenTrue);
+        const falseType = this.inferTypeFromNode(node.whenFalse);
+
+        if (trueType === falseType) {
+          return trueType;
+        }
+
+        return trueType === 'unknown' ? falseType : trueType;
+      }
+      if (ts.isParenthesizedExpression(node)) {
+        return this.inferTypeFromNode(node.expression);
+      }
+      if (ts.isBinaryExpression(node)) {
+        const operator = node.operatorToken.kind;
+        const isComparisonOperator =
+          operator === ts.SyntaxKind.EqualsEqualsToken ||
+          operator === ts.SyntaxKind.EqualsEqualsEqualsToken ||
+          operator === ts.SyntaxKind.ExclamationEqualsToken ||
+          operator === ts.SyntaxKind.ExclamationEqualsEqualsToken ||
+          operator === ts.SyntaxKind.LessThanToken ||
+          operator === ts.SyntaxKind.LessThanEqualsToken ||
+          operator === ts.SyntaxKind.GreaterThanToken ||
+          operator === ts.SyntaxKind.GreaterThanEqualsToken;
+
+        if (isComparisonOperator) {
+          return 'boolean';
+        }
+
+        const leftType = this.inferTypeFromNode(node.left);
+        const rightType = this.inferTypeFromNode(node.right);
+
+        return leftType === 'unknown' ? rightType : leftType;
+      }
+
+      // Get the type from TypeScript's type checker for more complex cases
+      const tsType = this.fileAnalyzer.typeChecker.getTypeAtLocation(node);
+      const typeFromTs = this.inferTypeFromTsType(tsType);
+
+      // Convert to our simplified type system
+      return typeFromTs;
+    } catch (error) {
+      console.error('Error inferring type from node:', error);
+      return 'unknown';
+    }
+  }
+
+  /**
+   * Tries to infer the type of a node and adds it to the structure
+   */
+  private inferAndAddType(path: string | StructuredPath, node: ts.Node): void {
+    // Use TypeScript's TypeChecker to get more accurate type information
+    const type = this.inferTypeFromNode(node);
+
+    // Add the type to the structure
+    this.addType(path, type);
+
+    // If this is a literal value being assigned to a property, extract the path
+    // This handles the case where we're processing a node that's part of an assignment
+    if (
+      ts.isNumericLiteral(node) ||
+      ts.isStringLiteral(node) ||
+      node.kind === ts.SyntaxKind.TrueKeyword ||
+      node.kind === ts.SyntaxKind.FalseKeyword
+    ) {
+      const literalValue = nodeToSource(node, this.sourceFile);
+      const pathStr = path.toString();
+      if (this.equivalentVariables[pathStr] === literalValue.toString()) {
+        this.addType(path, type);
+      }
+    }
+  }
+}