@sun-asterisk/sunlint 1.3.16 → 1.3.17

package/rules/common/C008/ts-morph-analyzer.js

@@ -0,0 +1,1067 @@
+/**
+ * C008 ts-morph Analyzer - Minimize Variable Scope (Declare Near Usage)
+ * 
+ * Uses ts-morph AST analysis to detect variables declared far from first usage.
+ * 100% accurate scope detection with proper handling of:
+ * - Function boundaries
+ * - Nested scopes
+ * - React hooks (useState, useEffect, etc.)
+ * - CSS-in-JS (keyframes, styled, css)
+ * - Ternary expressions
+ * - Module-level constants
+ * - Top-of-block declarations
+ * 
+ * Following Rule C005: Single responsibility
+ * Following Rule C006: Verb-noun naming
+ */
+
+const { Project, SyntaxKind, Node } = require('ts-morph');
+const path = require('path');
+const fs = require('fs');
+
+class C008TsMorphAnalyzer {
+  constructor(semanticEngine = null, options = {}) {
+    this.ruleId = 'C008';
+    this.ruleName = 'Minimize Variable Scope';
+    this.description = 'Variables should be declared close to their first usage';
+    this.semanticEngine = semanticEngine;
+    this.project = null;
+    this.verbose = false;
+
+    // Configuration
+    this.maxLineDistance = options.maxLineDistance || 10;
+    this.allowTopOfBlock = options.allowTopOfBlock !== undefined ? options.allowTopOfBlock : true;
+    this.ignoreConst = options.ignoreConst || false;
+  }
+
+  async initialize(semanticEngine = null) {
+    if (semanticEngine) {
+      this.semanticEngine = semanticEngine;
+    }
+    this.verbose = semanticEngine?.verbose || false;
+
+    // Use semantic engine's project if available
+    if (this.semanticEngine?.project) {
+      this.project = this.semanticEngine.project;
+      if (this.verbose) {
+        console.log('[DEBUG] 🎯 C008: Using semantic engine project');
+      }
+    } else {
+      this.project = new Project({
+        compilerOptions: {
+          target: 99, // Latest
+          module: 99, // ESNext
+          allowJs: true,
+          checkJs: false,
+          jsx: 2, // React
+        },
+      });
+      if (this.verbose) {
+        console.log('[DEBUG] 🎯 C008: Created standalone ts-morph project');
+      }
+    }
+  }
+
+  async analyze(files, language, options = {}) {
+    this.verbose = options.verbose || this.verbose;
+    
+    if (!this.project) {
+      await this.initialize();
+    }
+
+    const violations = [];
+
+    for (const filePath of files) {
+      try {
+        const fileViolations = await this.analyzeFile(filePath, options);
+        violations.push(...fileViolations);
+      } catch (error) {
+        if (this.verbose) {
+          console.warn(`[C008] Error analyzing ${filePath}:`, error.message);
+        }
+      }
+    }
+
+    return violations;
+  }
+
+  async analyzeFile(filePath, options = {}) {
+    // Get source file (may be in-memory or on disk)
+    let sourceFile = this.project.getSourceFile(filePath);
+    
+    // If not found and file exists on disk, add it
+    if (!sourceFile && fs.existsSync(filePath)) {
+      sourceFile = this.project.addSourceFileAtPath(filePath);
+    }
+    
+    if (!sourceFile) {
+      return []; // File not found in project
+    }
+
+    const violations = [];
+    
+    // Find all variable declarations
+    const variableDeclarations = sourceFile.getDescendantsOfKind(SyntaxKind.VariableDeclaration);
+
+    for (const declaration of variableDeclarations) {
+      const violation = this.checkVariableDeclaration(declaration, sourceFile);
+      if (violation) {
+        violations.push(violation);
+      }
+    }
+
+    return violations;
+  }
+
+  /**
+   * Check if variable declaration is too far from first usage
+   */
+  checkVariableDeclaration(declaration, sourceFile) {
+    const variableName = declaration.getName();
+    
+    // Skip destructured variables (e.g., const { a, b } = obj)
+    if (declaration.getParent().getKind() === SyntaxKind.ObjectBindingPattern ||
+        declaration.getParent().getKind() === SyntaxKind.ArrayBindingPattern) {
+      return null;
+    }
+
+    const initializer = declaration.getInitializer();
+    if (!initializer) {
+      return null; // No initializer, skip
+    }
+
+    // Skip React hooks
+    if (this.isReactHook(initializer)) {
+      return null;
+    }
+
+    // Skip CSS-in-JS
+    if (this.isCSSInJS(initializer)) {
+      return null;
+    }
+
+    // Skip function declarations
+    if (this.isFunctionDeclaration(initializer)) {
+      return null;
+    }
+
+    // Skip module-level constants
+    if (this.isModuleLevelConstant(declaration)) {
+      return null;
+    }
+
+    // Skip Redux Toolkit patterns (createSlice, createAsyncThunk, etc.)
+    if (this.isReduxPattern(declaration, initializer)) {
+      return null;
+    }
+
+    // Skip Redux initialState pattern
+    if (this.isReduxInitialState(declaration)) {
+      return null;
+    }
+
+    // Skip style configuration objects
+    if (this.isStyleConfig(declaration, initializer)) {
+      return null;
+    }
+
+    // Skip React component definitions
+    if (this.isReactComponentDefinition(declaration, initializer)) {
+      return null;
+    }
+
+    // Skip Storybook meta exports
+    if (this.isStoryBookMeta(declaration, sourceFile)) {
+      return null;
+    }
+
+    // Skip module-level variables declared at top of file (global singletons)
+    if (this.isModuleLevelTopDeclaration(declaration)) {
+      return null;
+    }
+
+    // Find first usage
+    const firstUsage = this.findFirstUsage(declaration, sourceFile);
+    if (!firstUsage) {
+      return null; // Variable not used or only in JSX
+    }
+
+    // Skip variables used only in JSX (React render pattern)
+    if (this.isUsedOnlyInJSX(declaration, firstUsage, sourceFile)) {
+      return null;
+    }
+
+    // Skip computed constants (UPPER_CASE + simple expression)
+    if (this.isComputedConstant(declaration, initializer)) {
+      return null;
+    }
+
+    // Skip React component top-level data declarations
+    if (this.isReactComponentTopDeclaration(declaration, sourceFile)) {
+      return null;
+    }
+
+    // Skip variables used immediately in return object
+    if (this.isUsedInReturnObject(declaration, firstUsage)) {
+      return null;
+    }
+
+    // Calculate distance
+    const declLine = declaration.getStartLineNumber();
+    const usageLine = firstUsage.getStartLineNumber();
+    const distance = this.calculateDistance(declaration, firstUsage, sourceFile);
+
+    if (distance <= this.maxLineDistance) {
+      return null; // Within acceptable range
+    }
+
+    // Distance > maxLineDistance - This is a violation
+    // Note: allowTopOfBlock option removed as it was too aggressive
+    // and caused false negatives (skipping legitimate violations)
+
+    // Create violation
+    return {
+      ruleId: this.ruleId,
+      message: `Variable '${variableName}' (line ${declLine}) is declared ${distance} lines before first use (max: ${this.maxLineDistance}). Consider moving declaration closer to usage.`,
+      severity: 'warning',
+      filePath: sourceFile.getFilePath(),
+      location: {
+        start: {
+          line: declLine,
+          column: declaration.getStart() - declaration.getStartLinePos() + 1
+        },
+        end: {
+          line: declaration.getEndLineNumber(),
+          column: declaration.getEnd() - declaration.getStartLinePos() + 1
+        }
+      },
+      context: {
+        variable: variableName,
+        declaredAt: declLine,
+        usedAt: usageLine,
+        distance: distance
+      }
+    };
+  }
+
+  /**
+   * Check if initializer is a React hook
+   */
+  isReactHook(initializer) {
+    if (Node.isCallExpression(initializer)) {
+      const expression = initializer.getExpression();
+      const text = expression.getText();
+      
+      // useState, useEffect, useRef, etc.
+      if (/^use[A-Z]/.test(text)) {
+        return true;
+      }
+      
+      // Form.useWatch, etc.
+      if (/\.[A-Z].*\.use[A-Z]/.test(text)) {
+        return true;
+      }
+    }
+    
+    return false;
+  }
+
+  /**
+   * Check if initializer is CSS-in-JS (keyframes, styled, css)
+   */
+  isCSSInJS(initializer) {
+    if (Node.isTaggedTemplateExpression(initializer)) {
+      const tag = initializer.getTag().getText();
+      return tag === 'keyframes' || tag === 'css' || tag.startsWith('styled.');
+    }
+    return false;
+  }
+
+  /**
+   * Check if initializer is a function declaration
+   */
+  isFunctionDeclaration(initializer) {
+    return Node.isArrowFunction(initializer) || 
+           Node.isFunctionExpression(initializer);
+  }
+
+  /**
+   * Check if variable is module-level constant (UPPER_CASE = literal/config)
+   * This covers:
+   * - const TYPE_DIGITAL_RELEASE = 'digital'
+   * - const DEFAULT_CONFIG = { ... }
+   * - const VALID_TYPES = ['a', 'b']
+   * - const MAX_RETRIES = 3
+   * - Pattern: Declare at top, export at bottom (e.g. storages.ts)
+   */
+  isModuleLevelConstant(declaration) {
+    const variableStatement = declaration.getFirstAncestorByKind(SyntaxKind.VariableStatement);
+    if (!variableStatement) {
+      return false;
+    }
+
+    // Check if at module level (not inside function/class)
+    const parent = variableStatement.getParent();
+    if (!Node.isSourceFile(parent)) {
+      return false;
+    }
+
+    // Check if const with UPPER_CASE naming
+    const declarationList = declaration.getParent();
+    if (declarationList.getDeclarationKind() !== 'const') {
+      return false;
+    }
+
+    const name = declaration.getName();
+    if (!/^[A-Z][A-Z0-9_]*$/.test(name)) {
+      return false;
+    }
+
+    // Check if exported (common pattern: declare at top, export at bottom)
+    const sourceFile = declaration.getSourceFile();
+    const exports = sourceFile.getExportSymbols();
+    const isExported = exports.some(exp => {
+      const expName = exp.getName();
+      return expName === name;
+    });
+    
+    if (isExported) {
+      return true;
+    }
+
+    // Check if constant-like value (literal or config object/array)
+    const initializer = declaration.getInitializer();
+    if (!initializer) {
+      return false;
+    }
+
+    const kind = initializer.getKind();
+
+    // Simple literals
+    if (Node.isNumericLiteral(initializer) ||
+        Node.isStringLiteral(initializer) ||
+        kind === SyntaxKind.TrueKeyword ||
+        kind === SyntaxKind.FalseKeyword ||
+        kind === SyntaxKind.NullKeyword ||
+        kind === SyntaxKind.UndefinedKeyword) {
+      return true;
+    }
+
+    // Template literals (const URL = `https://...`)
+    if (kind === SyntaxKind.TemplateExpression || kind === SyntaxKind.NoSubstitutionTemplateLiteral) {
+      return true;
+    }
+
+    // Object literals (const CONFIG = { ... })
+    if (kind === SyntaxKind.ObjectLiteralExpression) {
+      return true;
+    }
+
+    // Array literals (const TYPES = ['a', 'b', 'c'])
+    if (kind === SyntaxKind.ArrayLiteralExpression) {
+      return true;
+    }
+
+    // Enum-like member access (const STATUS = MyEnum.Active)
+    if (kind === SyntaxKind.PropertyAccessExpression) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Check if variable is Redux Toolkit pattern
+   * Covers:
+   * - createAsyncThunk
+   * - createSlice
+   * - createAction
+   * - createReducer
+   */
+  isReduxPattern(declaration, initializer) {
+    if (!Node.isCallExpression(initializer)) {
+      return false;
+    }
+
+    const expression = initializer.getExpression();
+    const text = expression.getText();
+
+    // Redux Toolkit functions
+    const reduxPatterns = [
+      'createAsyncThunk',
+      'createSlice',
+      'createAction',
+      'createReducer',
+      'createSelector',
+      'createEntityAdapter',
+    ];
+
+    return reduxPatterns.some(pattern => text.includes(pattern));
+  }
+
+  /**
+   * Check if variable is Storybook meta export
+   */
+  isStoryBookMeta(declaration, sourceFile) {
+    const name = declaration.getName();
+    
+    // Check if variable name is 'meta' or 'Meta'
+    if (name !== 'meta' && name !== 'Meta') {
+      return false;
+    }
+
+    // Check if file is a story file
+    const filePath = sourceFile.getFilePath();
+    if (!/\.stories\.(ts|tsx|js|jsx)$/.test(filePath)) {
+      return false;
+    }
+
+    // Check if it's exported as default
+    const variableStatement = declaration.getFirstAncestorByKind(SyntaxKind.VariableStatement);
+    if (!variableStatement) {
+      return false;
+    }
+
+    // Check if there's a default export of this meta
+    const sourceFileNode = declaration.getSourceFile();
+    const defaultExport = sourceFileNode.getDefaultExportSymbol();
+    if (defaultExport) {
+      const declarations = defaultExport.getDeclarations();
+      for (const decl of declarations) {
+        if (decl.getText().includes(name)) {
+          return true;
+        }
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Check if variable is Redux initialState pattern
+   * Pattern: const initialState: Type = { ... }
+   * This is a standard Redux Toolkit pattern where initialState
+   * must be defined before createSlice() call
+   */
+  isReduxInitialState(declaration) {
+    const name = declaration.getName();
+    
+    // Must be named 'initialState'
+    if (name !== 'initialState') {
+      return false;
+    }
+
+    // Check if in a Redux slice file
+    const sourceFile = declaration.getSourceFile();
+    const filePath = sourceFile.getFilePath();
+    const fileName = filePath.split('/').pop() || '';
+    
+    // Check if it's a slice file or contains Redux patterns
+    if (fileName.includes('Slice.ts') || fileName.includes('slice.ts')) {
+      return true;
+    }
+
+    // Alternative: Check if file contains createSlice
+    const fileText = sourceFile.getFullText();
+    if (fileText.includes('createSlice')) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Check if variable is a style configuration object
+   * Patterns:
+   * - const ButtonStyle: ComponentStyleConfig = { ... }
+   * - const xxxStyle = { baseStyle: {...}, variants: {...} }
+   * Used in Chakra UI, styled-components, theme configs
+   */
+  isStyleConfig(declaration, initializer) {
+    const name = declaration.getName();
+    
+    // Check if variable name ends with 'Style' or 'Styles'
+    if (name.endsWith('Style') || name.endsWith('Styles')) {
+      // Must be object literal
+      if (Node.isObjectLiteralExpression(initializer)) {
+        return true;
+      }
+    }
+
+    // Check type annotation for ComponentStyleConfig or similar
+    const typeNode = declaration.getTypeNode();
+    if (typeNode) {
+      const typeText = typeNode.getText();
+      if (typeText.includes('StyleConfig') || 
+          typeText.includes('ComponentStyle') ||
+          typeText.includes('ThemeConfig')) {
+        return true;
+      }
+    }
+
+    // Check if object contains common style config keys
+    if (Node.isObjectLiteralExpression(initializer)) {
+      const properties = initializer.getProperties();
+      const propNames = properties
+        .filter(p => Node.isPropertyAssignment(p))
+        .map(p => p.getName ? p.getName() : '');
+      
+      // Common style config properties
+      const styleConfigKeys = ['baseStyle', 'variants', 'sizes', 'defaultProps'];
+      const hasStyleKeys = styleConfigKeys.some(key => propNames.includes(key));
+      
+      if (hasStyleKeys) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Check if variable is a React component definition
+   * Patterns:
+   * - const Component = forwardRef<Props>(...)
+   * - const Component: React.FC<Props> = ...
+   */
+  isReactComponentDefinition(declaration, initializer) {
+    // Check if assigned to forwardRef()
+    if (Node.isCallExpression(initializer)) {
+      const expression = initializer.getExpression();
+      const text = expression.getText();
+      
+      if (text === 'forwardRef' || text.endsWith('.forwardRef')) {
+        return true;
+      }
+    }
+
+    // Check type annotation for React.FC or React.FunctionComponent
+    const typeNode = declaration.getTypeNode();
+    if (typeNode) {
+      const typeText = typeNode.getText();
+      if (typeText.includes('React.FC') || 
+          typeText.includes('React.FunctionComponent') ||
+          typeText.includes('FunctionComponent')) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Check if declaration is at top of function/block
+   */
+  isTopOfBlock(declaration) {
+    const block = declaration.getFirstAncestorByKind(SyntaxKind.Block);
+    if (!block) {
+      return false;
+    }
+
+    // Check if block is function body
+    const blockParent = block.getParent();
+    const isFunctionBlock = Node.isFunctionDeclaration(blockParent) ||
+                           Node.isFunctionExpression(blockParent) ||
+                           Node.isArrowFunction(blockParent) ||
+                           Node.isMethodDeclaration(blockParent);
+    
+    if (!isFunctionBlock) {
+      return false;
+    }
+
+    // Count statements from block start
+    const statements = block.getStatements();
+    const declStatement = declaration.getFirstAncestorByKind(SyntaxKind.VariableStatement);
+    if (!declStatement) {
+      return false;
+    }
+
+    const declIndex = statements.indexOf(declStatement);
+    
+    // Allow within first 10 statements
+    return declIndex < 10;
+  }
+
+  /**
+   * Check if declaration is module-level AND at top of file
+   * Pattern: Global singletons like axios instances, services
+   * Example:
+   *   const axiosApp = axios.create(...);  // Line 29
+   *   axiosApp.interceptors.request.use(...);
+   *   export default axiosApp;
+   */
+  isModuleLevelTopDeclaration(declaration) {
+    // Check if it's at module level (not inside function)
+    const scopeNode = this.getScopeNode(declaration);
+    if (!scopeNode || !Node.isSourceFile(scopeNode)) {
+      return false; // Not module-level
+    }
+
+    // Check if declared near top of file (within first 50 lines)
+    const declLine = declaration.getStartLineNumber();
+    const MAX_TOP_LINES = 50;
+    
+    if (declLine > MAX_TOP_LINES) {
+      return false; // Too far from top
+    }
+
+    // Additional check: Common singleton patterns
+    const initializer = declaration.getInitializer();
+    if (!initializer) {
+      return false;
+    }
+
+    const initText = initializer.getText();
+    
+    // Check for common singleton patterns
+    const singletonPatterns = [
+      'axios.create',
+      '.create(',
+      'new ',
+      'createClient',
+      'createInstance',
+    ];
+
+    const isSingletonPattern = singletonPatterns.some(pattern => 
+      initText.includes(pattern)
+    );
+
+    return isSingletonPattern;
+  }
+
+  /**
+   * Check if variable is used only in JSX (React render pattern)
+   * Pattern: const menuList = [...]; return <>{menuList.map(...)}</>
+   * These are data declarations for rendering, acceptable pattern
+   */
+  isUsedOnlyInJSX(declaration, firstUsage, sourceFile) {
+    // Check if first usage is inside JSX
+    let current = firstUsage.getParent();
+    while (current && current !== sourceFile) {
+      if (Node.isJsxElement(current) || 
+          Node.isJsxSelfClosingElement(current) ||
+          Node.isJsxFragment(current) ||
+          Node.isJsxExpression(current)) {
+        return true; // Used in JSX
+      }
+      current = current.getParent();
+    }
+    return false;
+  }
+
+  /**
+   * Check if variable is a computed constant (UPPER_CASE + simple expression)
+   * Pattern: const SP_LANDSCAPE = window.orientation === 90 || ...
+   * These are derived constants, acceptable even if far from usage
+   */
+  isComputedConstant(declaration, initializer) {
+    const name = declaration.getName();
+    
+    // Check UPPER_CASE naming convention
+    if (!/^[A-Z][A-Z0-9_]*$/.test(name)) {
+      return false;
+    }
+
+    // Check if it's a simple expression (comparison, logical, etc.)
+    if (Node.isBinaryExpression(initializer) ||
+        Node.isConditionalExpression(initializer) ||
+        Node.isPrefixUnaryExpression(initializer)) {
+      return true;
+    }
+
+    // Check if it's accessing property/method (e.g., window.orientation)
+    if (Node.isPropertyAccessExpression(initializer) ||
+        Node.isElementAccessExpression(initializer)) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Check if variable is declared at top of React component function
+   * Pattern: Variables declared alongside hooks (useState, useEffect, etc.)
+   * Example:
+   *   const Component = () => {
+   *     const [state, setState] = useState(...);  // Hook
+   *     const router = useRouter();               // Hook
+   *     const dataCheck = Storage.get(...);       // Data declaration ← SKIP
+   *     
+   *     useEffect(() => { use(dataCheck); }, []); // Far away but acceptable
+   *     return <div>{dataCheck}</div>;
+   *   };
+   */
+  isReactComponentTopDeclaration(declaration, sourceFile) {
+    // Check if inside a function (arrow or regular)
+    const parentFunc = declaration.getFirstAncestor(node =>
+      Node.isArrowFunction(node) ||
+      Node.isFunctionExpression(node) ||
+      Node.isFunctionDeclaration(node)
+    );
+
+    if (!parentFunc) {
+      return false; // Not in function
+    }
+
+    // Check if this function is a React component
+    // Heuristic: Has JSX return statement or uses React hooks
+    const funcBody = Node.isArrowFunction(parentFunc) || Node.isFunctionExpression(parentFunc)
+      ? parentFunc.getBody()
+      : Node.isFunctionDeclaration(parentFunc)
+      ? parentFunc.getBody()
+      : null;
+
+    if (!funcBody || !Node.isBlock(funcBody)) {
+      return false; // No block body
+    }
+
+    // Check if function body has JSX or hooks
+    const hasJSX = funcBody.getDescendantsOfKind(SyntaxKind.JsxElement).length > 0 ||
+                   funcBody.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement).length > 0 ||
+                   funcBody.getDescendantsOfKind(SyntaxKind.JsxFragment).length > 0;
+
+    if (!hasJSX) {
+      return false; // Not a React component
+    }
+
+    // Check if declaration is in top statements of component (within first 30 statements)
+    const statements = funcBody.getStatements();
+    const declStatement = declaration.getFirstAncestorByKind(SyntaxKind.VariableStatement);
+    
+    if (!declStatement) {
+      return false;
+    }
+
+    const declIndex = statements.indexOf(declStatement);
+    if (declIndex === -1 || declIndex >= 30) {
+      return false; // Too far from top
+    }
+
+    // Check if there are hooks nearby (useState, useEffect, etc.)
+    // If yes, this is likely a React component top declaration
+    const nearbyStatements = statements.slice(Math.max(0, declIndex - 5), Math.min(statements.length, declIndex + 5));
+    const hasNearbyHooks = nearbyStatements.some(stmt => {
+      const text = stmt.getText();
+      return /use[A-Z]\w+/.test(text); // Match useXxx hooks
+    });
+
+    return hasNearbyHooks;
+  }
+
+  /**
+   * Check if variable is used in a return object/statement
+   * Pattern: const x = ...; return { x, ... } or return x;
+   * 
+   * Example (SKIP):
+   *   const dataset_attributes = !dataset ? undefined : { ...dataset };
+   *   const other = ...;
+   *   return { dataset_attributes, other };
+   * 
+   * Logic: If variable is ONLY used in the final return statement,
+   * it's a "prepare and return" pattern - acceptable.
+   */
+  isUsedInReturnObject(declaration, firstUsage) {
+    if (!firstUsage) {
+      return false;
+    }
+
+    // Find the return statement containing this usage
+    const returnStmt = firstUsage.getFirstAncestor(node =>
+      Node.isReturnStatement(node)
+    );
+
+    if (!returnStmt) {
+      return false;
+    }
+
+    // Get parent block
+    const declStatement = declaration.getFirstAncestorByKind(SyntaxKind.VariableStatement);
+    if (!declStatement) {
+      return false;
+    }
+
+    const parentBlock = declStatement.getFirstAncestor(node => Node.isBlock(node));
+    if (!parentBlock) {
+      return false;
+    }
+
+    const statements = parentBlock.getStatements();
+    const returnIndex = statements.indexOf(returnStmt);
+
+    if (returnIndex === -1) {
+      return false;
+    }
+
+    // Check if return is the last (or near-last) statement in block
+    // Pattern: Variables declared in middle of function, then used in final return
+    // This is acceptable "prepare data and return" pattern
+    const isNearEnd = returnIndex >= statements.length - 2;
+    
+    if (!isNearEnd) {
+      return false; // Return is not at end, not a "prepare and return" pattern
+    }
+
+    // Check if variable is ONLY used in this return (not used elsewhere)
+    const variableName = declaration.getName();
+    const allUsages = parentBlock.getDescendantsOfKind(SyntaxKind.Identifier)
+      .filter(id => {
+        if (id.getText() !== variableName || id === declaration.getNameNode()) {
+          return false;
+        }
+        
+        // Skip if it's another declaration
+        const parent = id.getParent();
+        if (Node.isVariableDeclaration(parent) || Node.isBindingElement(parent)) {
+          return false;
+        }
+        
+        // Skip if it's part of property access (e.g., params.dataset_attributes)
+        // We only want standalone references
+        if (Node.isPropertyAccessExpression(parent) && parent.getNameNode() === id) {
+          return false; // This is a property name, not a variable reference
+        }
+        
+        return true;
+      });
+
+    // Count usages outside the return statement
+    const usagesOutsideReturn = allUsages.filter(usage => {
+      const usageReturn = usage.getFirstAncestor(node => Node.isReturnStatement(node));
+      return usageReturn !== returnStmt;
+    });
+
+    // If variable is only used in the return, it's a "prepare and return" pattern
+    return usagesOutsideReturn.length === 0;
+  }
+
+  /**
+   * Find first usage of variable
+   */
+  findFirstUsage(declaration, sourceFile) {
+    const variableName = declaration.getName();
+    
+    // Get containing function/block scope
+    const scopeNode = this.getScopeNode(declaration);
+    if (!scopeNode) {
+      return null;
+    }
+
+    const declPos = declaration.getEnd();
+    let firstUsage = null;
+    let firstUsagePos = Infinity;
+
+    // Find all identifiers with same name in scope
+    const identifiers = scopeNode.getDescendantsOfKind(SyntaxKind.Identifier);
+    
+    for (const identifier of identifiers) {
+      if (identifier.getText() !== variableName) {
+        continue;
+      }
+
+      const pos = identifier.getStart();
+      
+      // Skip if before declaration
+      if (pos <= declPos) {
+        continue;
+      }
+
+      // Skip if it's the declaration itself
+      if (identifier.getParent() === declaration) {
+        continue;
+      }
+
+      // Skip if it's another variable declaration (destructuring, etc.)
+      const parent = identifier.getParent();
+      if (Node.isVariableDeclaration(parent) || Node.isBindingElement(parent)) {
+        continue; // This is a declaration, not a usage
+      }
+
+      // Skip if it's an assignment target (property name in object literal)
+      if (Node.isPropertyAssignment(parent) && parent.getName() === variableName) {
+        // Check if it's {variableName} shorthand or {variableName: value}
+        if (parent.getInitializer()?.getText() === variableName) {
+          // It's shorthand {variableName}, this IS a usage
+        } else {
+          continue; // It's {variableName: value}, skip
+        }
+      }
+
+      // Skip JSX attribute names (but not values)
+      if (Node.isJsxAttribute(parent)) {
+        const attrName = parent.getNameNode();
+        if (attrName === identifier) {
+          continue; // It's attribute name, skip
+        }
+      }
+
+      // This is a usage
+      if (pos < firstUsagePos) {
+        firstUsagePos = pos;
+        firstUsage = identifier;
+      }
+    }
+
+    return firstUsage;
+  }
+
+  /**
+   * Get scope node for variable (function/block it belongs to)
+   */
+  getScopeNode(declaration) {
+    // Find containing function
+    const func = declaration.getFirstAncestor(node => 
+      Node.isFunctionDeclaration(node) ||
+      Node.isFunctionExpression(node) ||
+      Node.isArrowFunction(node) ||
+      Node.isMethodDeclaration(node) ||
+      Node.isConstructorDeclaration(node)
+    );
+
+    if (func) {
+      return func;
+    }
+
+    // Module-level variable
+    return declaration.getSourceFile();
+  }
+
+  /**
+   * Calculate real distance between declaration and usage
+   * Distance = number of statements between declaration and usage
+   * This represents logical distance, not line distance
+   * 
+   * Examples:
+   *   const a = 1;        // Statement 1
+   *   const b = 2;        // Statement 2 (distance = 1)
+   *   console.log(a);     // Usage
+   * 
+   *   const x = condition  // Statement 1 (multi-line ternary = 1 statement)
+   *     ? {...}
+   *     : {...};
+   *   const y = 2;        // Statement 2 (distance = 1, not 10 lines)
+   *   use(x);             // Usage
+   */
+  calculateDistance(declaration, usage, sourceFile) {
+    // Try to count statements first (more accurate)
+    const stmtDistance = this.countStatementsBetween(declaration, usage);
+    if (stmtDistance !== null) {
+      return stmtDistance;
+    }
+    
+    // Fallback to line distance for edge cases
+    const declEndLine = declaration.getEndLineNumber();
+    const usageLine = usage.getStartLineNumber();
+    return usageLine - declEndLine;
+  }
+
+  /**
+   * Count number of statements between declaration and usage
+   * Returns null if statements cannot be counted (e.g., different scopes)
+   */
+  countStatementsBetween(declaration, usage) {
+    // Get the statement nodes (not just the declarations)
+    const declStatement = declaration.getFirstAncestorByKind(SyntaxKind.VariableStatement) ||
+                         declaration.getFirstAncestorByKind(SyntaxKind.ExpressionStatement);
+    
+    if (!declStatement) {
+      return null; // Cannot find statement
+    }
+
+    // Find the block/body containing both declaration and usage
+    const commonBlock = this.findCommonBlock(declStatement, usage);
+    if (!commonBlock) {
+      return null; // Different scopes
+    }
+
+    // Get all statements in the block
+    let statements = [];
+    if (Node.isSourceFile(commonBlock)) {
+      statements = commonBlock.getStatements();
+    } else if (Node.isBlock(commonBlock)) {
+      statements = commonBlock.getStatements();
+    } else if (Node.isCaseClause(commonBlock) || Node.isDefaultClause(commonBlock)) {
+      statements = commonBlock.getStatements();
+    } else {
+      return null; // Unknown block type
+    }
+
+    // Find indices
+    const declIndex = statements.indexOf(declStatement);
+    if (declIndex === -1) {
+      return null;
+    }
+
+    // Find statement containing usage
+    const usageStatement = this.findStatementContaining(statements, usage);
+    if (!usageStatement) {
+      return null;
+    }
+
+    const usageIndex = statements.indexOf(usageStatement);
+    if (usageIndex === -1 || usageIndex <= declIndex) {
+      return null;
+    }
+
+    // Count distance from declaration to usage (exclusive on both ends)
+    // usageIndex - declIndex = number of statements from decl to usage
+    // Example: decl at 0, usage at 11 = 11 statements distance
+    return usageIndex - declIndex;
+  }
+
+  /**
+   * Find common block containing both nodes
+   */
+  findCommonBlock(node1, node2) {
+    // Get all ancestor blocks for node1
+    const blocks1 = [];
+    let current = node1.getParent();
+    while (current) {
+      if (Node.isSourceFile(current) || 
+          Node.isBlock(current) || 
+          Node.isCaseClause(current) || 
+          Node.isDefaultClause(current)) {
+        blocks1.push(current);
+      }
+      current = current.getParent();
+    }
+
+    // Find first common block with node2
+    current = node2.getParent();
+    while (current) {
+      if (blocks1.includes(current)) {
+        return current;
+      }
+      current = current.getParent();
+    }
+
+    return null;
+  }
+
+  /**
+   * Find the statement containing a node
+   */
+  findStatementContaining(statements, node) {
+    for (const stmt of statements) {
+      if (this.isNodeInside(node, stmt)) {
+        return stmt;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Check if node is inside ancestor
+   */
+  isNodeInside(node, ancestor) {
+    let current = node;
+    while (current) {
+      if (current === ancestor) {
+        return true;
+      }
+      current = current.getParent();
+    }
+    return false;
+  }
+}
+
+module.exports = C008TsMorphAnalyzer;