@sun-asterisk/sungen 1.0.0

package/src/generators/ui-model-builder/deep-scanner.ts

@@ -0,0 +1,1244 @@
+/**
+ * PRODUCTION-READY Deep Scanner
+ * Implements all 4 iterations:
+ * 1. Deep Scanning (4+ levels)
+ * 2. UI Library Handling
+ * 3. Props Merging
+ * 4. Smart Filtering
+ */
+
+import * as parser from '@babel/parser';
+import traverse from '@babel/traverse';
+import * as t from '@babel/types';
+import * as fs from 'fs';
+import * as path from 'path';
+import { UIElement } from '../types';
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+interface DeepScanConfig {
+  sourceRoot: string;
+  projectRoot: string;
+  maxDepth: number;
+  verbose?: boolean;
+}
+
+// ============================================================================
+// Framework Components Registry
+// ============================================================================
+
+interface FrameworkComponentDef {
+  convertTo: string;           // Target DOM element (e.g., 'a', 'img')
+  role?: string;               // ARIA role
+  propsMap: Record<string, string | ((attrs: any) => any)>;  // Props mapping
+  defaultProps?: Record<string, any>;
+}
+
+const FRAMEWORK_COMPONENTS: Record<string, Record<string, FrameworkComponentDef>> = {
+  // Next.js Framework Components
+  'next/link': {
+    Link: {
+      convertTo: 'a',
+      role: 'link',
+      propsMap: {
+        href: 'href',
+        // Next.js Link wraps children in <a>, so we preserve all props
+      }
+    }
+  },
+  'next/image': {
+    Image: {
+      convertTo: 'img',
+      role: 'img',
+      propsMap: {
+        src: 'src',
+        alt: 'alt',
+        width: 'width',
+        height: 'height',
+        loading: 'loading',
+        priority: (attrs: any) => attrs.priority ? 'eager' : 'lazy'
+      }
+    }
+  },
+  'next/script': {
+    Script: {
+      convertTo: 'script',
+      propsMap: {
+        src: 'src',
+        strategy: 'strategy',
+        onLoad: 'onload'
+      }
+    }
+  },
+
+  // React Router Components (for future support)
+  'react-router-dom': {
+    Link: {
+      convertTo: 'a',
+      role: 'link',
+      propsMap: {
+        to: 'href'  // React Router uses 'to' instead of 'href'
+      }
+    },
+    NavLink: {
+      convertTo: 'a',
+      role: 'link',
+      propsMap: {
+        to: 'href'
+      }
+    }
+  },
+
+  // Remix Framework Components (for future support)
+  'remix': {
+    Link: {
+      convertTo: 'a',
+      role: 'link',
+      propsMap: {
+        to: 'href'
+      }
+    },
+    Form: {
+      convertTo: 'form',
+      role: 'form',
+      propsMap: {
+        action: 'action',
+        method: 'method'
+      }
+    }
+  }
+};
+
+// UI libraries to scan (don't skip these)
+const UI_LIBRARIES = [
+  'flowbite-react',
+  '@mui/material',
+  '@mui/icons-material',
+  'antd',
+  'react-bootstrap',
+  '@headlessui/react',
+  '@radix-ui',
+  'chakra-ui',
+  '@chakra-ui/react',
+  'semantic-ui-react',
+  '@fluentui/react'
+];
+
+// Skip these patterns (REFINED - don't skip framework UI components)
+const SKIP_PATTERNS = [
+  /^react$/,
+  /^react-dom$/,
+  /^next$/,                    // Skip 'next' core package
+  /^next\/navigation$/,        // Skip navigation hooks (not UI)
+  /^next\/headers$/,           // Skip headers (not UI)
+  /^next\/server$/,            // Skip server utilities (not UI)
+  /^next\/font/,               // Skip font utilities (not UI)
+  // NOTE: We DON'T skip 'next/link', 'next/image', 'next/script' anymore!
+  /Icon$/,
+  /^Logo$/,
+  /^Copyright$/,
+  /^RenderIf$/,
+  /^Fragment$/
+];
+
+// Prioritize scanning these patterns
+const PRIORITY_PATTERNS = [
+  /Input$/,
+  /Field$/,
+  /Select$/,
+  /Checkbox$/,
+  /Radio$/,
+  /Button$/,
+  /TextArea$/,
+  /Form$/,
+  /TextField$/,
+  /Switch$/,
+  /Slider$/
+];
+
+// ============================================================================
+// Deep Scanner Class
+// ============================================================================
+
+export class DeepScanner {
+  private config: DeepScanConfig;
+  private elements: UIElement[] = [];
+  private elementCounter = 0;
+  private scannedFiles = new Set<string>(); // Track file+props combinations
+  private componentCache = new Map<string, any>(); // Cache parsed components
+
+  constructor(config: DeepScanConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Main entry point - scan files deeply
+   */
+  async scanFiles(filePaths: string[]): Promise<UIElement[]> {
+    this.elements = [];
+    this.elementCounter = 0;
+    this.scannedFiles.clear();
+
+    for (const filePath of filePaths) {
+      await this.scanFile(filePath, 0, {});
+    }
+
+    return this.elements;
+  }
+
+  /**
+   * Check if component should be scanned
+   */
+  private shouldScanComponent(componentName: string, importPath: string): boolean {
+    // Skip patterns
+    if (SKIP_PATTERNS.some(pattern => pattern.test(componentName))) {
+      return false;
+    }
+
+    if (SKIP_PATTERNS.some(pattern => pattern.test(importPath))) {
+      return false;
+    }
+
+    // Always scan priority components
+    if (PRIORITY_PATTERNS.some(pattern => pattern.test(componentName))) {
+      return true;
+    }
+
+    // Scan UI library components
+    if (UI_LIBRARIES.some(lib => importPath.includes(lib))) {
+      return true;
+    }
+
+    // Scan custom components (starts with uppercase)
+    if (/^[A-Z]/.test(componentName)) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Check if this is an actual DOM element OR a UI library component
+   * We treat UI library components as terminal elements (don't scan deeper)
+   */
+  private isActualDOMElement(tagName: string): boolean {
+    const domElements = [
+      'input', 'button', 'textarea', 'select', 'form',
+      'a', 'img', 'video', 'audio', 'canvas',
+      'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+      'p', 'span', 'div', 'section', 'article',
+      'table', 'tr', 'td', 'th', 'thead', 'tbody',
+      'ul', 'ol', 'li', 'dl', 'dt', 'dd',
+      'label', 'fieldset', 'legend'
+    ];
+
+    return domElements.includes(tagName.toLowerCase());
+  }
+
+  /**
+   * Check if this is a UI library component (flowbite, MUI, etc.)
+   * These are treated as "actual elements" for our purposes
+   */
+  private isUILibraryComponent(tagName: string, importPath: string): boolean {
+    // Check if from UI library
+    const isFromUILibrary = UI_LIBRARIES.some(lib => importPath.includes(lib));
+
+    if (!isFromUILibrary) return false;
+
+    // For UI libraries, check if it's a form/interactive component
+    // (not layout/utility components like Flowbite, ThemeProvider, etc.)
+    const uiComponentPatterns = [
+      /Input/i,       // TextInput, InputText, Input, EmailInput
+      /TextField/i,
+      /Button/i,
+      /Select/i,
+      /Checkbox/i,
+      /Radio/i,
+      /Switch/i,
+      /Slider/i,
+      /TextArea/i,
+      /Dropdown/i,
+      /Modal/i,
+      /Dialog/i,
+      /Picker/i,      // DatePicker, TimePicker
+      /Toggle/i
+    ];
+
+    const matchesPattern = uiComponentPatterns.some(pattern => pattern.test(tagName));
+
+    // Skip utility components
+    const utilityComponents = ['Flowbite', 'ThemeProvider', 'Label', 'HelperText'];
+    const isUtility = utilityComponents.some(util => tagName.includes(util));
+
+    return matchesPattern && !isUtility;
+  }
+
+  /**
+   * Check if component is a custom wrapper of UI library component
+   * E.g., Button wraps ButtonFlowbite, TextInput wraps InputText
+   * These should be treated as terminal elements (buttons/inputs)
+   */
+  private isCustomUIWrapper(componentName: string, importPath: string): boolean {
+    // Not from UI library (it's custom)
+    const isFromUILib = UI_LIBRARIES.some(lib => importPath.includes(lib));
+    if (isFromUILib) return false;
+
+    // Must be from project's components
+    if (!importPath.includes('@/components')) return false;
+
+    // Match patterns that suggest it's a UI wrapper
+    const wrapperPatterns = [
+      /Button$/i,     // Button, SubmitButton, etc.
+      /Input$/i,      // TextInput, EmailInput, etc.
+      /Select$/i,
+      /Checkbox$/i,
+      /Radio$/i,
+      /TextArea$/i,
+      /Switch$/i,
+      /Slider$/i,
+      /Link$/i        // Custom Link components
+    ];
+
+    return wrapperPatterns.some(pattern => pattern.test(componentName));
+  }
+
+  /**
+   * Check if component is a framework component (Next.js, React Router, etc.)
+   * Returns component definition if found, null otherwise
+   */
+  private getFrameworkComponent(componentName: string, importPath: string): FrameworkComponentDef | null {
+    // Check if import path is in FRAMEWORK_COMPONENTS registry
+    if (!FRAMEWORK_COMPONENTS[importPath]) {
+      return null;
+    }
+
+    // Check if component name exists for this import path
+    const componentDef = FRAMEWORK_COMPONENTS[importPath][componentName];
+    return componentDef || null;
+  }
+
+  /**
+   * Map framework component props to target DOM element props
+   */
+  private mapFrameworkProps(
+    attrs: Record<string, any>,
+    propsMap: Record<string, string | ((attrs: any) => any)>
+  ): Record<string, any> {
+    const mapped: Record<string, any> = {};
+
+    // Map each prop according to propsMap
+    for (const [sourceKey, targetKey] of Object.entries(propsMap)) {
+      if (attrs[sourceKey] !== undefined) {
+        if (typeof targetKey === 'function') {
+          // Custom mapping function
+          mapped[sourceKey] = targetKey(attrs);
+        } else {
+          // Direct prop name mapping
+          mapped[targetKey] = attrs[sourceKey];
+        }
+      }
+    }
+
+    // Preserve unmapped props that might be useful
+    const mappedKeys = new Set(Object.keys(propsMap));
+    for (const [key, value] of Object.entries(attrs)) {
+      if (!mappedKeys.has(key) && !mapped[key]) {
+        // Keep useful attributes like className, id, data-testid, etc.
+        if (['className', 'id', 'data-testid', 'aria-label', 'aria-labelledby', 'role'].includes(key)) {
+          mapped[key] = value;
+        }
+      }
+    }
+
+    return mapped;
+  }
+
+  /**
+   * Convert framework component to synthetic DOM element
+   */
+  private convertFrameworkComponent(
+    componentName: string,
+    componentDef: FrameworkComponentDef,
+    attrs: Record<string, any>,
+    text: string | null,
+    sourceFileName: string
+  ): UIElement {
+    // Map props according to component definition
+    const mappedProps = this.mapFrameworkProps(attrs, componentDef.propsMap);
+
+    // Apply default props if any
+    const finalProps = {
+      ...componentDef.defaultProps,
+      ...mappedProps
+    };
+
+    // Create synthetic element
+    const element: UIElement = {
+      key: `e${++this.elementCounter}`,
+      tag: componentDef.convertTo,
+      role: componentDef.role || this.inferRole(componentDef.convertTo),
+      id: finalProps.id,
+      name: finalProps.name,
+      placeholder: finalProps.placeholder,
+      ariaLabel: finalProps['aria-label'] || finalProps.ariaLabel,
+      testId: finalProps['data-testid'],
+      text: text,
+      source: sourceFileName,
+      props: finalProps
+    };
+
+    // Add metadata to track this was converted from framework component
+    (element as any).metadata = {
+      frameworkComponent: componentName,
+      originalImport: 'framework' // Will be set by caller
+    };
+
+    return element;
+  }
+
+  /**
+   * Try to resolve a path with different file extensions
+   */
+  private tryResolveWithExtensions(basePath: string): string | null {
+    const extensions = ['.tsx', '.ts', '.jsx', '.js'];
+
+    // Try direct file with extensions
+    for (const ext of extensions) {
+      const fullPath = basePath + ext;
+      if (fs.existsSync(fullPath)) {
+        return fullPath;
+      }
+    }
+
+    // Try index files
+    for (const ext of extensions) {
+      const indexPath = path.join(basePath, `index${ext}`);
+      if (fs.existsSync(indexPath)) {
+        return indexPath;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Resolve import path to actual file path
+   * Enhanced to try multiple locations for @/ alias
+   */
+  private resolveComponentPath(importPath: string, sourceFile: string): string | null {
+    try {
+      // Handle @ alias - Try multiple locations (Next.js, CRA, custom)
+      if (importPath.startsWith('@/')) {
+        const relativePath = importPath.replace('@/', '');
+
+        // Try multiple candidate directories in priority order
+        const candidates = [
+          path.join(this.config.projectRoot, 'src', relativePath),      // CRA, Vite: src/
+          path.join(this.config.projectRoot, 'app', relativePath),      // Next.js 13+: app/
+          path.join(this.config.projectRoot, relativePath),             // Root level
+          path.join(this.config.sourceRoot, '..', relativePath),        // Relative to sourceRoot
+        ];
+
+        for (const candidate of candidates) {
+          const resolved = this.tryResolveWithExtensions(candidate);
+          if (resolved) {
+            if (this.config.verbose) {
+              console.log(`    ✓ Resolved @/${relativePath} → ${path.relative(this.config.projectRoot, resolved)}`);
+            }
+            return resolved;
+          }
+        }
+
+        // If not found, log for debugging
+        if (this.config.verbose) {
+          console.log(`    ⚠️  Could not resolve @/${relativePath} (tried: src/, app/, root/)`);
+        }
+        return null;
+      }
+
+      // Handle relative imports
+      else if (importPath.startsWith('./') || importPath.startsWith('../')) {
+        const sourceDir = path.dirname(sourceFile);
+        const resolvedPath = path.resolve(sourceDir, importPath);
+        return this.tryResolveWithExtensions(resolvedPath);
+      }
+
+      // Handle UI library imports (node_modules)
+      else if (UI_LIBRARIES.some(lib => importPath.includes(lib))) {
+        const nodeModulesPath = path.join(this.config.projectRoot, 'node_modules', importPath);
+
+        // Try with extensions first
+        const resolved = this.tryResolveWithExtensions(nodeModulesPath);
+        if (resolved) return resolved;
+
+        // Try package.json main/module field
+        const pkgPath = path.join(nodeModulesPath, 'package.json');
+        if (fs.existsSync(pkgPath)) {
+          try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+            const mainFile = pkg.module || pkg.main || 'index.js';
+            const mainPath = path.join(nodeModulesPath, mainFile);
+            if (fs.existsSync(mainPath)) {
+              return mainPath;
+            }
+          } catch (e) {
+            // Ignore package.json parse errors
+          }
+        }
+
+        return null;
+      }
+
+      // Skip other node_modules
+      else {
+        return null;
+      }
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Extract JSX element from conditional expression (ignoring the condition)
+   * This allows us to discover elements in modals, conditional blocks, etc.
+   */
+  private extractConditionalJSXElement(
+    jsxElement: any,
+    sourceFileName: string,
+    imports: Map<string, string>,
+    componentProps: Record<string, any>,
+    depth: number,
+    detectedComponents: Array<{ name: string; importPath: string; props: Record<string, any>; isProjectComponent?: boolean }>
+  ): void {
+    const openingElement = jsxElement.openingElement;
+    let tagName = '';
+
+    if (openingElement.name.type === 'JSXIdentifier') {
+      tagName = openingElement.name.name;
+    }
+
+    if (this.config.verbose && depth === 2) {
+      console.log(`  ${'  '.repeat(depth)}  🔄 Conditional JSX: <${tagName}>`);
+    }
+
+    // Extract attributes and merge with component props
+    const attrs = this.extractAttributes(openingElement.attributes, componentProps);
+    const text = this.extractTextContent(jsxElement);
+    const mergedAttrs = this.mergeProps(componentProps, attrs);
+
+    // Check if custom component (Modal, Button, Input, etc.)
+    if (/^[A-Z]/.test(tagName) && imports.has(tagName)) {
+      const importPath = imports.get(tagName)!;
+
+      // Check if it's a project component that should be deep scanned
+      if (importPath.startsWith('@/') || importPath.startsWith('./') || importPath.startsWith('../')) {
+        if (this.config.verbose) {
+          console.log(`  ${'  '.repeat(depth)}  🔄 Conditional component: <${tagName}> - adding to scan queue`);
+        }
+
+        // Add to detectedComponents queue for deep scanning
+        // This ensures <Input>, <Button>, etc. get fully scanned
+        detectedComponents.push({
+          name: tagName,
+          importPath,
+          props: mergedAttrs,  // Use merged props for prop resolution
+          isProjectComponent: true
+        });
+
+        // Also recursively scan immediate JSX children (for containers like <Modal>)
+        // This will discover HTML elements and additional custom components
+        if (jsxElement.children && jsxElement.children.length > 0) {
+          for (const child of jsxElement.children) {
+            if (child.type === 'JSXElement') {
+              this.extractConditionalJSXElement(child, sourceFileName, imports, componentProps, depth, detectedComponents);
+            } else if (child.type === 'JSXExpressionContainer') {
+              const expr = child.expression;
+              if (expr.type === 'LogicalExpression' && expr.operator === '&&' && expr.right.type === 'JSXElement') {
+                this.extractConditionalJSXElement(expr.right, sourceFileName, imports, componentProps, depth, detectedComponents);
+              } else if (expr.type === 'ConditionalExpression') {
+                if (expr.consequent.type === 'JSXElement') {
+                  this.extractConditionalJSXElement(expr.consequent, sourceFileName, imports, componentProps, depth, detectedComponents);
+                }
+                if (expr.alternate && expr.alternate.type === 'JSXElement') {
+                  this.extractConditionalJSXElement(expr.alternate, sourceFileName, imports, componentProps, depth, detectedComponents);
+                }
+              }
+            }
+          }
+        }
+      }
+
+      return;  // Don't add component itself as element
+    }
+
+    // HTML element - add directly
+    if (this.shouldIncludeElement(tagName, mergedAttrs, text)) {
+      this.elements.push({
+        key: `e${++this.elementCounter}`,
+        tag: tagName,
+        role: this.inferRole(tagName),
+        id: mergedAttrs.id,
+        name: mergedAttrs.name,
+        placeholder: mergedAttrs.placeholder,
+        ariaLabel: mergedAttrs['aria-label'] || mergedAttrs.ariaLabel,
+        testId: mergedAttrs['data-testid'],
+        text: text,
+        source: sourceFileName,
+        props: mergedAttrs
+      });
+
+      if (this.config.verbose) {
+        console.log(`  ${'  '.repeat(depth)}  ✅ Found conditional element: <${tagName}> ${mergedAttrs['aria-label'] || mergedAttrs.ariaLabel ? `aria-label="${mergedAttrs['aria-label'] || mergedAttrs.ariaLabel}"` : ''}${text ? `text="${text.substring(0, 30)}"` : ''}`);
+      }
+    }
+
+    // Recursively process children
+    if (jsxElement.children && jsxElement.children.length > 0) {
+      for (const child of jsxElement.children) {
+        if (child.type === 'JSXElement') {
+          this.extractConditionalJSXElement(child, sourceFileName, imports, componentProps, depth, detectedComponents);
+        } else if (child.type === 'JSXExpressionContainer') {
+          // Handle nested conditionals
+          const expr = child.expression;
+
+          if (expr.type === 'LogicalExpression' && expr.operator === '&&' && expr.right.type === 'JSXElement') {
+            this.extractConditionalJSXElement(expr.right, sourceFileName, imports, componentProps, depth, detectedComponents);
+          } else if (expr.type === 'ConditionalExpression') {
+            if (expr.consequent.type === 'JSXElement') {
+              this.extractConditionalJSXElement(expr.consequent, sourceFileName, imports, componentProps, depth, detectedComponents);
+            }
+            if (expr.alternate && expr.alternate.type === 'JSXElement') {
+              this.extractConditionalJSXElement(expr.alternate, sourceFileName, imports, componentProps, depth, detectedComponents);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Extract attributes from JSX element
+   * Now supports resolving expressions from componentProps!
+   */
+  private extractAttributes(attributes: any[], componentProps: Record<string, any> = {}): Record<string, any> {
+    const attrs: Record<string, any> = {};
+
+    attributes.forEach(attr => {
+      if (attr.type !== 'JSXAttribute' || attr.name.type !== 'JSXIdentifier') {
+        return;
+      }
+
+      const attrName = attr.name.name;
+      let value: any = null;
+
+      if (!attr.value) {
+        value = true; // Boolean attribute like <input required />
+      } else if (attr.value.type === 'StringLiteral') {
+        value = attr.value.value;
+      } else if (attr.value.type === 'JSXExpressionContainer') {
+        const expr = attr.value.expression;
+
+        if (expr.type === 'BooleanLiteral') {
+          value = expr.value;
+        } else if (expr.type === 'StringLiteral') {
+          value = expr.value;
+        } else if (expr.type === 'NumericLiteral') {
+          value = expr.value;
+        } else if (expr.type === 'MemberExpression') {
+          // props.name → try to resolve from componentProps
+          if (expr.object.type === 'Identifier' && expr.object.name === 'props' &&
+              expr.property.type === 'Identifier') {
+            const propName = expr.property.name;
+
+            // Try to resolve from componentProps
+            if (componentProps[propName] !== undefined) {
+              value = componentProps[propName];  // ✅ RESOLVED!
+            } else {
+              // Keep as expression if can't resolve
+              value = `{props.${propName}}`;
+            }
+          }
+        } else if (expr.type === 'Identifier') {
+          // Handle: className={inputClassName}
+          // Try to resolve from componentProps
+          const identifierName = expr.name;
+          if (componentProps[identifierName] !== undefined) {
+            value = componentProps[identifierName];  // ✅ RESOLVED!
+          } else {
+            // Keep as expression
+            value = `{${identifierName}}`;
+          }
+        } else if (expr.type === 'CallExpression') {
+          // Handle: register('email', ...) → extract first string argument
+          if (expr.arguments && expr.arguments.length > 0) {
+            const firstArg = expr.arguments[0];
+            if (firstArg.type === 'StringLiteral') {
+              // register('email') → use 'email' as value
+              value = firstArg.value;  // ✅ EXTRACTED!
+            }
+          }
+        }
+      }
+
+      if (value !== null) {
+        attrs[attrName] = value;
+      }
+    });
+
+    return attrs;
+  }
+
+  /**
+   * Extract text content from JSX element
+   */
+  private extractTextContent(node: any): string | null {
+    let text = '';
+
+    if (!node.children) return null;
+
+    node.children.forEach((child: any) => {
+      if (child.type === 'JSXText') {
+        const trimmed = child.value.trim();
+        if (trimmed) {
+          text += trimmed + ' ';
+        }
+      } else if (child.type === 'JSXExpressionContainer') {
+        if (child.expression.type === 'StringLiteral') {
+          text += child.expression.value + ' ';
+        }
+      }
+    });
+
+    return text.trim() || null;
+  }
+
+  /**
+   * Check if element should be included in UI model
+   */
+  private shouldIncludeElement(tagName: string, attrs: Record<string, any>, text: string | null): boolean {
+    const lowercaseTag = tagName.toLowerCase();
+
+    // Priority 1: UI library components (ALWAYS include)
+    if (lowercaseTag.includes('input') || lowercaseTag.includes('button') || lowercaseTag.includes('select')) {
+      return true;
+    }
+
+    // Priority 2: Form elements (ALWAYS include)
+    const formElements = ['input', 'button', 'textarea', 'select', 'form'];
+    if (formElements.includes(lowercaseTag)) return true;
+
+    // Priority 2: Links
+    if (lowercaseTag === 'a' || tagName === 'Link') return true;
+
+    // Priority 3: Elements with identifiers
+    if (attrs.id || attrs.name || attrs['data-testid'] || attrs['aria-label']) {
+      return true;
+    }
+
+    // Priority 4: Headings with text
+    if (/^h[1-6]$/.test(lowercaseTag) && text) return true;
+
+    // Priority 5: Images with alt
+    if (lowercaseTag === 'img' && attrs.alt) return true;
+
+    // Priority 6: Interactive elements
+    if (attrs.onClick || attrs.onSubmit || attrs.href) return true;
+
+    // Skip generic containers unless meaningful
+    if (['div', 'span', 'p'].includes(lowercaseTag)) {
+      return !!(text && text.length > 5); // Only if meaningful text
+    }
+
+    // Include semantic elements
+    if (['section', 'article', 'nav', 'header', 'footer', 'main'].includes(lowercaseTag)) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Merge props from component chain
+   */
+  private mergeProps(componentProps: Record<string, any>, elementAttrs: Record<string, any>): Record<string, any> {
+    const merged = { ...componentProps };
+
+    // Element attributes override component props
+    Object.entries(elementAttrs).forEach(([key, value]) => {
+      // Handle prop expressions like {props.name}
+      if (typeof value === 'string' && value.startsWith('{props.')) {
+        const propName = value.match(/\{props\.(\w+)\}/)?.[1];
+        if (propName && componentProps[propName]) {
+          merged[key] = componentProps[propName];
+        } else {
+          merged[key] = value; // Keep expression as-is
+        }
+      } else {
+        merged[key] = value;
+      }
+    });
+
+    return merged;
+  }
+
+  /**
+   * Generate cache key for file+props combination
+   * This allows same component to be scanned multiple times with different props
+   */
+  private getCacheKey(filePath: string, componentProps: Record<string, any>): string {
+    // Create a stable key from significant props (id, name, ariaLabel, etc.)
+    const significantProps = ['id', 'name', 'ariaLabel', 'aria-label', 'placeholder', 'type', 'testId', 'data-testid'];
+    const propsSignature = significantProps
+      .map(key => componentProps[key] || componentProps[key.replace(/-/g, '')])
+      .filter(Boolean)
+      .join('|');
+
+    return `${filePath}::${propsSignature}`;
+  }
+
+  /**
+   * Recursively scan a file for UI elements
+   */
+  private async scanFile(
+    filePath: string,
+    depth: number,
+    componentProps: Record<string, any>
+  ): Promise<void> {
+    // Safety checks
+    if (depth >= this.config.maxDepth) {
+      if (this.config.verbose) {
+        console.log(`  ${'  '.repeat(depth)}⚠️  Max depth ${this.config.maxDepth} reached`);
+      }
+      return;
+    }
+
+    // Use cache key based on file+props to allow same component with different props
+    const cacheKey = this.getCacheKey(filePath, componentProps);
+    if (this.scannedFiles.has(cacheKey)) {
+      if (this.config.verbose) {
+        console.log(`  ${'  '.repeat(depth)}⚠️  Already scanned: ${path.basename(filePath)} with these props`);
+      }
+      return;
+    }
+
+    if (!fs.existsSync(filePath)) {
+      if (this.config.verbose) {
+        console.log(`  ${'  '.repeat(depth)}⚠️  File not found: ${filePath}`);
+      }
+      return;
+    }
+
+    this.scannedFiles.add(cacheKey);
+
+    if (this.config.verbose) {
+      console.log(`  ${'  '.repeat(depth)}📄 Scanning (L${depth}): ${path.basename(filePath)}`);
+    }
+
+    // Read and parse file
+    const code = fs.readFileSync(filePath, 'utf-8');
+    let ast;
+
+    try {
+      ast = parser.parse(code, {
+        sourceType: 'module',
+        plugins: ['typescript', 'jsx']
+      });
+    } catch (error) {
+      if (this.config.verbose) {
+        console.log(`  ${'  '.repeat(depth)}⚠️  Parse error: ${(error as Error).message}`);
+      }
+      return;
+    }
+
+    // Extract imports and JSX elements
+    const self = this;  // Capture 'this' and avoid naming conflict
+    const sourceFileName = path.basename(filePath);
+    const imports = new Map<string, string>();
+    const detectedComponents: Array<{ name: string; importPath: string; props: Record<string, any>; isProjectComponent?: boolean }> = [];
+    let jsxElementCount = 0;
+
+    traverse(ast, {
+      ImportDeclaration: (path: any) => {
+        const importPath = path.node.source.value;
+
+        // Default import
+        const defaultSpec = path.node.specifiers.find((s: any) => s.type === 'ImportDefaultSpecifier');
+        if (defaultSpec) {
+          imports.set(defaultSpec.local.name, importPath);
+        }
+
+        // Named imports
+        path.node.specifiers
+          .filter((s: any) => s.type === 'ImportSpecifier')
+          .forEach((spec: any) => {
+            if (spec.imported.type === 'Identifier') {
+              // Use LOCAL name (after 'as'), not imported name
+              imports.set(spec.local.name, importPath);
+
+              if (self.config.verbose && depth === 2) {
+                console.log(`  ${'  '.repeat(depth)}  Import: ${spec.imported.name} as ${spec.local.name} from ${importPath}`);
+              }
+            }
+          });
+      }
+    });
+
+    // Extract JSX elements
+
+    traverse(ast, {
+      JSXElement: (nodePath: any) => {
+        jsxElementCount++;
+        const openingElement = nodePath.node.openingElement;
+        let tagName = '';
+
+        if (openingElement.name.type === 'JSXIdentifier') {
+          tagName = openingElement.name.name;
+        }
+
+        if (self.config.verbose && depth === 2) {
+          console.log(`  ${'  '.repeat(depth)}  JSX #${jsxElementCount}: <${tagName}>`);
+        }
+
+        // Extract attributes WITH componentProps for expression resolution
+        const attrs = self.extractAttributes(openingElement.attributes, componentProps);
+        const text = self.extractTextContent(nodePath.node);
+
+        // Merge with component props (for additional props not in attrs)
+        const mergedAttrs = self.mergeProps(componentProps, attrs);
+
+        // Check if custom component
+        if (/^[A-Z]/.test(tagName) && imports.has(tagName)) {
+          const importPath = imports.get(tagName)!;
+
+          if (self.config.verbose) {
+            console.log(`  ${'  '.repeat(depth)}  🔎 Component: <${tagName}> from ${importPath}`);
+          }
+
+          // NEW: Check if framework component (Next.js Link, Image, etc.)
+          const frameworkComp = self.getFrameworkComponent(tagName, importPath);
+          if (frameworkComp) {
+            // Convert to synthetic DOM element
+            const syntheticElement = self.convertFrameworkComponent(
+              tagName,
+              frameworkComp,
+              mergedAttrs,
+              text,
+              sourceFileName
+            );
+
+            // Update metadata with actual import path
+            (syntheticElement as any).metadata.originalImport = importPath;
+
+            // Add to elements
+            self.elements.push(syntheticElement);
+
+            if (self.config.verbose) {
+              console.log(`  ${'  '.repeat(depth)}  ✅ Found Framework Component: <${tagName}> → <${frameworkComp.convertTo}> ${mergedAttrs.href ? `href="${mergedAttrs.href}"` : ''}${text ? `text="${text.substring(0, 30)}"` : ''}`);
+            }
+
+            // Don't scan deeper - framework components are terminal
+            return;
+          }
+
+          // Check if UI library component - treat as terminal element
+          const isUILib = self.isUILibraryComponent(tagName, importPath);
+
+          if (self.config.verbose && depth === 2) {
+            console.log(`  ${'  '.repeat(depth)}    isUILibraryComponent(${tagName}, ${importPath}) = ${isUILib}`);
+          }
+
+          if (isUILib) {
+            // Treat as actual element (don't scan deeper)
+            if (self.shouldIncludeElement(tagName, mergedAttrs, text)) {
+              self.elements.push({
+                key: `e${++self.elementCounter}`,
+                tag: tagName.toLowerCase(),  // e.g. "inputtext"
+                role: self.inferRole('input'),  // Infer as input
+                id: mergedAttrs.id,
+                name: mergedAttrs.name,
+                placeholder: mergedAttrs.placeholder,
+                ariaLabel: mergedAttrs['aria-label'] || mergedAttrs.ariaLabel,
+                testId: mergedAttrs['data-testid'],
+                text: text,
+                source: sourceFileName,
+                props: mergedAttrs
+              });
+
+              if (self.config.verbose) {
+                console.log(`  ${'  '.repeat(depth)}  ✅ Found UI Library: <${tagName}> ${mergedAttrs.id ? `id="${mergedAttrs.id}"` : ''}${mergedAttrs['data-testid'] ? `data-testid="${mergedAttrs['data-testid']}"` : ''}`);
+              }
+            }
+          }
+          // NEW: Project components - ALWAYS try to scan deeper
+          else if (importPath.startsWith('@/') || importPath.startsWith('./') || importPath.startsWith('../')) {
+            // This is a project component - add to scan queue
+            // We'll scan it after traverse completes (cannot await in traverse callback)
+            if (self.config.verbose) {
+              console.log(`  ${'  '.repeat(depth)}  → Will scan project component: <${tagName}>`);
+            }
+
+            detectedComponents.push({
+              name: tagName,
+              importPath,
+              props: mergedAttrs,  // Use merged props (includes component props)
+              isProjectComponent: true  // Mark as project component
+            });
+          }
+          // For other components (3rd party libs not in UI_LIBRARIES), decide whether to scan
+          else if (self.shouldScanComponent(tagName, importPath)) {
+            detectedComponents.push({
+              name: tagName,
+              importPath,
+              props: attrs,
+              isProjectComponent: false
+            });
+          }
+        }
+        // Check if actual DOM element
+        else if (self.isActualDOMElement(tagName)) {
+          // Found actual element - include it!
+          if (self.shouldIncludeElement(tagName, mergedAttrs, text)) {
+            self.elements.push({
+              key: `e${++self.elementCounter}`,
+              tag: tagName.toLowerCase(),
+              role: self.inferRole(tagName),
+              id: mergedAttrs.id,
+              name: mergedAttrs.name,
+              placeholder: mergedAttrs.placeholder,
+              ariaLabel: mergedAttrs['aria-label'] || mergedAttrs.ariaLabel,
+              testId: mergedAttrs['data-testid'],
+              text: text,
+              source: sourceFileName,
+              props: mergedAttrs
+            });
+
+            if (self.config.verbose) {
+              console.log(`  ${'  '.repeat(depth)}  ✅ Found: <${tagName}> ${mergedAttrs.id ? `id="${mergedAttrs.id}"` : ''}${mergedAttrs['data-testid'] ? `data-testid="${mergedAttrs['data-testid']}"` : ''}`);
+            }
+          }
+        }
+      },
+
+      // NEW: Handle conditional rendering - ignore conditions, scan all JSX
+      JSXExpressionContainer: (nodePath: any) => {
+        const expr = nodePath.node.expression;
+
+        // Pattern 1: Logical AND (condition && <Element />)
+        if (expr.type === 'LogicalExpression' && expr.operator === '&&') {
+          const rightSide = expr.right;
+
+          if (rightSide.type === 'JSXElement') {
+            // Extract element from condition, ignoring the condition itself
+            self.extractConditionalJSXElement(rightSide, sourceFileName, imports, componentProps, depth, detectedComponents);
+          } else if (rightSide.type === 'JSXFragment') {
+            // Handle {condition && (<><Element1 /><Element2 /></>)}
+            for (const child of rightSide.children) {
+              if (child.type === 'JSXElement') {
+                self.extractConditionalJSXElement(child, sourceFileName, imports, componentProps, depth, detectedComponents);
+              }
+            }
+          }
+        }
+
+        // Pattern 2: Ternary operator (condition ? <A /> : <B />)
+        if (expr.type === 'ConditionalExpression') {
+          const consequent = expr.consequent;
+          const alternate = expr.alternate;
+
+          // Extract BOTH branches (we want all possible UI)
+          if (consequent.type === 'JSXElement') {
+            self.extractConditionalJSXElement(consequent, sourceFileName, imports, componentProps, depth, detectedComponents);
+          }
+
+          if (alternate && alternate.type === 'JSXElement') {
+            self.extractConditionalJSXElement(alternate, sourceFileName, imports, componentProps, depth, detectedComponents);
+          }
+        }
+
+        // Pattern 3: Array.map() rendering
+        if (expr.type === 'CallExpression') {
+          const callee = expr.callee;
+
+          if (callee.type === 'MemberExpression' &&
+              callee.property.type === 'Identifier' &&
+              callee.property.name === 'map') {
+            const mapCallback = expr.arguments[0];
+
+            if (mapCallback &&
+                (mapCallback.type === 'ArrowFunctionExpression' ||
+                 mapCallback.type === 'FunctionExpression')) {
+              const body = mapCallback.body;
+
+              // Direct return: arr.map(item => <Element />)
+              if (body.type === 'JSXElement') {
+                self.extractConditionalJSXElement(body, sourceFileName, imports, componentProps, depth, detectedComponents);
+              }
+
+              // Block with return: arr.map(item => { return <Element /> })
+              if (body.type === 'BlockStatement') {
+                for (const statement of body.body) {
+                  if (statement.type === 'ReturnStatement' &&
+                      statement.argument &&
+                      statement.argument.type === 'JSXElement') {
+                    self.extractConditionalJSXElement(statement.argument, sourceFileName, imports, componentProps, depth, detectedComponents);
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    });
+
+    if (this.config.verbose && detectedComponents.length > 0) {
+      console.log(`  ${'  '.repeat(depth)}  → Found ${detectedComponents.length} component(s) to scan deeper`);
+    }
+
+    // Recursively scan detected components
+    for (const comp of detectedComponents) {
+      const componentPath = this.resolveComponentPath(comp.importPath, filePath);
+
+      if (componentPath) {
+        const elementsBefore = this.elements.length;
+
+        if (this.config.verbose) {
+          console.log(`  ${'  '.repeat(depth)}  → Diving into: ${comp.name}`);
+        }
+
+        await this.scanFile(componentPath, depth + 1, comp.props);
+
+        const elementsAfter = this.elements.length;
+        const elementsFound = elementsAfter - elementsBefore;
+
+        // Project components: Check if found elements, if not, try fallback
+        if ((comp as any).isProjectComponent && elementsFound === 0) {
+          // No elements found inside project component - try fallback as wrapper
+          if (this.config.verbose) {
+            console.log(`  ${'  '.repeat(depth)}  ⚠️  <${comp.name}> scanned but empty, trying wrapper fallback`);
+          }
+
+          if (this.isCustomUIWrapper(comp.name, comp.importPath)) {
+            // Extract as synthetic element
+            const { tag: elementType, role } = this.inferWrapperType(comp.name);
+
+            this.elements.push({
+              key: `e${++this.elementCounter}`,
+              tag: elementType,
+              role: role,
+              id: comp.props.id,
+              name: comp.props.name,
+              placeholder: comp.props.placeholder,
+              ariaLabel: comp.props['aria-label'] || comp.props.ariaLabel,
+              testId: comp.props['data-testid'],
+              text: null,
+              source: sourceFileName,
+              props: comp.props
+            });
+
+            if (this.config.verbose) {
+              console.log(`  ${'  '.repeat(depth)}  ✅ Fallback: Extracted <${comp.name}> as ${elementType}`);
+            }
+          }
+        } else if (this.config.verbose && elementsFound > 0) {
+          console.log(`  ${'  '.repeat(depth)}  ✅ Scanned <${comp.name}> → found ${elementsFound} element(s)`);
+        }
+      } else {
+        // Cannot resolve path
+        if (this.config.verbose) {
+          console.log(`  ${'  '.repeat(depth)}  ⚠️  Could not resolve: ${comp.name} from ${comp.importPath}`);
+        }
+
+        // For project components that cannot be resolved, try wrapper fallback
+        if ((comp as any).isProjectComponent && this.isCustomUIWrapper(comp.name, comp.importPath)) {
+          const { tag: elementType, role } = this.inferWrapperType(comp.name);
+
+          this.elements.push({
+            key: `e${++this.elementCounter}`,
+            tag: elementType,
+            role: role,
+            id: comp.props.id,
+            name: comp.props.name,
+            placeholder: comp.props.placeholder,
+            ariaLabel: comp.props['aria-label'] || comp.props.ariaLabel,
+            testId: comp.props['data-testid'],
+            text: null,
+            source: sourceFileName,
+            props: comp.props
+          });
+
+          if (this.config.verbose) {
+            console.log(`  ${'  '.repeat(depth)}  ✅ Fallback (unresolved): Extracted <${comp.name}> as ${elementType}`);
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Infer wrapper type from component name
+   * Used for fallback when component is empty
+   */
+  private inferWrapperType(componentName: string): { tag: string; role: string } {
+    if (/Input$/i.test(componentName)) {
+      return { tag: 'input', role: 'textbox' };
+    } else if (/TextArea$/i.test(componentName)) {
+      return { tag: 'textarea', role: 'textbox' };
+    } else if (/Select$/i.test(componentName)) {
+      return { tag: 'select', role: 'combobox' };
+    } else if (/Link$/i.test(componentName)) {
+      return { tag: 'a', role: 'link' };
+    } else if (/Button$/i.test(componentName)) {
+      return { tag: 'button', role: 'button' };
+    } else {
+      // Default to div
+      return { tag: 'div', role: undefined as any };
+    }
+  }
+
+  /**
+   * Infer semantic role from tag name
+   */
+  private inferRole(tagName: string): string | undefined {
+    const roleMap: Record<string, string> = {
+      'button': 'button',
+      'a': 'link',
+      'input': 'textbox',
+      'textarea': 'textbox',
+      'select': 'combobox',
+      'img': 'img',
+      'nav': 'navigation',
+      'main': 'main',
+      'header': 'banner',
+      'footer': 'contentinfo'
+    };
+
+    return roleMap[tagName.toLowerCase()];
+  }
+
+  /**
+   * Get scan results with statistics
+   */
+  getResults() {
+    const byTag: Record<string, number> = {};
+    const formElements = [];
+
+    this.elements.forEach(el => {
+      byTag[el.tag] = (byTag[el.tag] || 0) + 1;
+
+      const formTags = ['input', 'button', 'textarea', 'select', 'form'];
+      if (formTags.includes(el.tag)) {
+        formElements.push(el);
+      }
+    });
+
+    return {
+      totalElements: this.elements.length,
+      filesScanned: this.scannedFiles.size,
+      byTag,
+      formElements,
+      elements: this.elements
+    };
+  }
+}