@sun-asterisk/sungen 1.0.0

package/src/core/ui-scanner/heuristics/base-heuristic.ts

@@ -0,0 +1,216 @@
+/**
+ * Base Heuristic Interface
+ * All element detection heuristics implement this interface
+ */
+
+import * as t from '@babel/types';
+import { UIElement } from '../scanner-interface';
+
+export interface ElementHeuristic {
+  /**
+   * Heuristic name for debugging
+   */
+  readonly name: string;
+
+  /**
+   * Detect if a JSX element matches this heuristic
+   */
+  matches(node: t.JSXElement | t.JSXFragment, context: HeuristicContext): boolean;
+
+  /**
+   * Extract UI element information from matched node
+   */
+  extract(node: t.JSXElement | t.JSXFragment, context: HeuristicContext): UIElement | null;
+}
+
+/**
+ * Context passed to heuristics for element detection
+ */
+export interface HeuristicContext {
+  /**
+   * Current component name
+   */
+  componentName?: string;
+
+  /**
+   * Parent component name
+   */
+  parentComponent?: string;
+
+  /**
+   * Current depth in component tree
+   */
+  depth?: number;
+
+  /**
+   * Element counter for ID generation
+   */
+  elementCounter: number;
+
+  /**
+   * Increment element counter
+   */
+  incrementCounter(): void;
+
+  /**
+   * File path being scanned
+   */
+  filePath?: string;
+}
+
+/**
+ * Helper functions for heuristics
+ */
+export class HeuristicHelpers {
+  /**
+   * Get JSX element name (e.g., "input", "Button")
+   */
+  static getElementName(node: t.JSXElement): string | null {
+    const openingElement = node.openingElement;
+    if (t.isJSXIdentifier(openingElement.name)) {
+      return openingElement.name.name;
+    }
+    if (t.isJSXMemberExpression(openingElement.name)) {
+      // Handle cases like <Form.Input>
+      return this.getMemberExpressionName(openingElement.name);
+    }
+    return null;
+  }
+
+  /**
+   * Get member expression name (e.g., "Form.Input" -> "Input")
+   */
+  private static getMemberExpressionName(expr: t.JSXMemberExpression): string {
+    if (t.isJSXIdentifier(expr.property)) {
+      return expr.property.name;
+    }
+    return '';
+  }
+
+  /**
+   * Get attribute value from JSX element
+   */
+  static getAttributeValue(node: t.JSXElement, attrName: string): string | null {
+    const attr = node.openingElement.attributes.find(
+      (a): a is t.JSXAttribute =>
+        t.isJSXAttribute(a) && t.isJSXIdentifier(a.name) && a.name.name === attrName
+    );
+
+    if (!attr) return null;
+
+    if (t.isStringLiteral(attr.value)) {
+      return attr.value.value;
+    }
+
+    if (t.isJSXExpressionContainer(attr.value)) {
+      const expr = attr.value.expression;
+      if (t.isStringLiteral(expr)) {
+        return expr.value;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Check if element has attribute
+   */
+  static hasAttribute(node: t.JSXElement, attrName: string): boolean {
+    return node.openingElement.attributes.some(
+      (a) => t.isJSXAttribute(a) && t.isJSXIdentifier(a.name) && a.name.name === attrName
+    );
+  }
+
+  /**
+   * Get all attributes as key-value pairs
+   */
+  static getAllAttributes(node: t.JSXElement): Record<string, string> {
+    const attrs: Record<string, string> = {};
+
+    for (const attr of node.openingElement.attributes) {
+      if (t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name)) {
+        const value = this.getAttributeValue(node, attr.name.name);
+        if (value) {
+          attrs[attr.name.name] = value;
+        }
+      }
+    }
+
+    return attrs;
+  }
+
+  /**
+   * Generate element ID from attributes
+   */
+  static generateElementId(node: t.JSXElement, counter: number): string {
+    // Priority: id > data-testid > name > placeholder > generated
+    const id = this.getAttributeValue(node, 'id');
+    if (id) return id;
+
+    const testId = this.getAttributeValue(node, 'data-testid');
+    if (testId) return testId;
+
+    const name = this.getAttributeValue(node, 'name');
+    if (name) return name;
+
+    const placeholder = this.getAttributeValue(node, 'placeholder');
+    if (placeholder) {
+      return placeholder.toLowerCase().replace(/\s+/g, '-');
+    }
+
+    const elementName = this.getElementName(node);
+    return `${elementName || 'element'}-${counter}`;
+  }
+
+  /**
+   * Build CSS selector for element
+   */
+  static buildSelector(node: t.JSXElement): string {
+    const elementName = this.getElementName(node);
+    if (!elementName) return '';
+
+    const selectors: string[] = [elementName.toLowerCase()];
+
+    // Add attribute selectors
+    const id = this.getAttributeValue(node, 'id');
+    if (id) {
+      selectors.push(`#${id}`);
+    }
+
+    const className = this.getAttributeValue(node, 'className');
+    if (className) {
+      const classes = className.split(/\s+/).filter(c => c && !c.includes('${'));
+      if (classes.length > 0) {
+        selectors.push(`.${classes.join('.')}`);
+      }
+    }
+
+    const testId = this.getAttributeValue(node, 'data-testid');
+    if (testId) {
+      selectors.push(`[data-testid="${testId}"]`);
+    }
+
+    const placeholder = this.getAttributeValue(node, 'placeholder');
+    if (placeholder && !placeholder.includes('${')) {
+      selectors.push(`[placeholder="${placeholder}"]`);
+    }
+
+    return selectors.join('');
+  }
+
+  /**
+   * Check if element is a form control
+   */
+  static isFormControl(elementName: string): boolean {
+    const formControls = ['input', 'textarea', 'select', 'button'];
+    return formControls.includes(elementName.toLowerCase());
+  }
+
+  /**
+   * Check if element name suggests it's a custom component
+   */
+  static isCustomComponent(elementName: string): boolean {
+    // Custom components start with uppercase
+    return /^[A-Z]/.test(elementName);
+  }
+}

package/src/core/ui-scanner/react-scanner.ts

@@ -0,0 +1,156 @@
+/**
+ * React UI Scanner
+ * Refactored implementation that conforms to UIScanner interface
+ * Uses DeepScanner for high-quality element detection
+ */
+
+import { UIScanner, UIModel, UIElement, ScanStats } from './scanner-interface';
+import { RuntimeConfig } from '../../config/config-schema';
+import { DeepScanner } from '../../generators/ui-model-builder/deep-scanner';
+import * as path from 'path';
+import * as fs from 'fs';
+
+export class ReactScanner implements UIScanner {
+  readonly name = 'ReactScanner';
+  readonly framework = 'react' as const;
+
+  private config: RuntimeConfig;
+  private deepScanner: DeepScanner;
+
+  constructor(config: RuntimeConfig) {
+    this.config = config;
+
+    // Initialize DeepScanner with config
+    this.deepScanner = new DeepScanner({
+      sourceRoot: config.paths.sourceRoot,
+      projectRoot: process.cwd(),
+      maxDepth: config.scanner.maxDepth,
+      verbose: config.verbose
+    });
+  }
+
+  /**
+   * Scan a screen and generate UI model
+   */
+  async scan(screenName: string, config: RuntimeConfig): Promise<UIModel> {
+    const startTime = Date.now();
+
+    // Find screen files
+    const screenFiles = this.findScreenFiles(screenName);
+
+    if (config.verbose) {
+      console.log(`  Scanning ${screenFiles.length} file(s) for screen: ${screenName}`);
+      screenFiles.forEach(f => console.log(`    - ${path.relative(process.cwd(), f)}`));
+    }
+
+    // Use DeepScanner to scan files
+    // @ts-ignore - DeepScanner elements compatible but different type definition
+    const elements = await this.deepScanner.scanFiles(screenFiles);
+
+    if (config.verbose) {
+      console.log(`  Found ${elements.length} elements`);
+    }
+
+    // Build UI model
+    const uiModel: UIModel = {
+      screen: screenName,
+      timestamp: Date.now(),
+      framework: this.framework,
+      sourceFiles: screenFiles.map(f => path.relative(process.cwd(), f)),
+      elements: elements as any, // Type cast - DeepScanner elements are compatible
+      stats: {
+        totalComponents: 0, // DeepScanner doesn't track this
+        totalElements: elements.length,
+        maxDepth: config.scanner.maxDepth,
+        scanDuration: Date.now() - startTime,
+        filesScanned: screenFiles.length
+      }
+    };
+
+    return uiModel;
+  }
+
+  /**
+   * Validate scanner can run
+   */
+  validate(): boolean {
+    return fs.existsSync(this.config.paths.sourceRoot);
+  }
+
+  /**
+   * Find all source files for a screen
+   * Looks for: app/{screen}/page.tsx, app/{screen}/page.jsx, etc.
+   */
+  private findScreenFiles(screenName: string): string[] {
+    const files: string[] = [];
+    const sourceRoot = this.config.paths.sourceRoot;
+
+    // Convert screen name to possible paths
+    // auth-login -> auth/login
+    const screenPath = screenName.replace(/-/g, '/');
+
+    // Possible file patterns
+    const patterns = [
+      path.join(sourceRoot, screenPath, 'page.tsx'),
+      path.join(sourceRoot, screenPath, 'page.jsx'),
+      path.join(sourceRoot, screenPath, 'index.tsx'),
+      path.join(sourceRoot, screenPath, 'index.jsx'),
+      path.join(sourceRoot, `${screenName}.tsx`),
+      path.join(sourceRoot, `${screenName}.jsx`),
+      path.join(sourceRoot, 'page.tsx'), // Root page for "home"
+      path.join(sourceRoot, 'layout.tsx') // Always include layout
+    ];
+
+    // Add files that exist
+    for (const pattern of patterns) {
+      if (fs.existsSync(pattern) && !files.includes(pattern)) {
+        files.push(pattern);
+      }
+    }
+
+    return files;
+  }
+
+  /**
+   * Discover all available screens
+   */
+  async discoverScreens(): Promise<string[]> {
+    const screens: string[] = [];
+    const sourceRoot = this.config.paths.sourceRoot;
+
+    if (!fs.existsSync(sourceRoot)) {
+      return screens;
+    }
+
+    // Scan sourceRoot for directories with page.tsx/jsx files
+    const scanDir = (dir: string, prefix = '') => {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const fullPath = path.join(dir, entry.name);
+          const hasPageFile = fs.existsSync(path.join(fullPath, 'page.tsx')) ||
+                            fs.existsSync(path.join(fullPath, 'page.jsx'));
+
+          if (hasPageFile) {
+            const screenName = prefix ? `${prefix}-${entry.name}` : entry.name;
+            screens.push(screenName);
+          }
+
+          // Recursively scan subdirectories
+          scanDir(fullPath, prefix ? `${prefix}-${entry.name}` : entry.name);
+        }
+      }
+    };
+
+    scanDir(sourceRoot);
+
+    // Add "home" if root page exists
+    if (fs.existsSync(path.join(sourceRoot, 'page.tsx')) ||
+        fs.existsSync(path.join(sourceRoot, 'page.jsx'))) {
+      screens.unshift('home');
+    }
+
+    return screens;
+  }
+}

package/src/core/ui-scanner/scanner-interface.ts

@@ -0,0 +1,133 @@
+/**
+ * UI Scanner Interface
+ * Defines the contract for UI scanning implementations
+ * Supports multiple frameworks: React, Vue, Angular, etc.
+ */
+
+import { RuntimeConfig } from '../../config/config-schema';
+
+/**
+ * Main Scanner Interface
+ */
+export interface UIScanner {
+  /**
+   * Scanner name/type
+   */
+  readonly name: string;
+
+  /**
+   * Supported framework
+   */
+  readonly framework: 'react' | 'vue' | 'angular';
+
+  /**
+   * Scan a screen and generate UI model
+   *
+   * @param screenName - Screen identifier (e.g., 'chat', 'login')
+   * @param config - Runtime configuration
+   * @returns UI Model
+   */
+  scan(screenName: string, config: RuntimeConfig): Promise<UIModel>;
+
+  /**
+   * Validate scanner can run in current environment
+   */
+  validate(): boolean;
+}
+
+/**
+ * UI Model Structure
+ * Represents discovered UI elements for a screen
+ */
+export interface UIModel {
+  screen: string;
+  timestamp: number;
+  framework: string;
+  sourceFiles: string[];
+  elements: UIElement[];
+  stats: ScanStats;
+}
+
+/**
+ * UI Element
+ * Represents a discovered UI element
+ */
+export interface UIElement {
+  id: string;                    // Suggested ID (e.g., 'message-input')
+  type: ElementType;             // Element type (input, button, etc.)
+  selector: string;              // CSS selector to locate element
+  label?: string;                // Associated label text
+  placeholder?: string;          // Placeholder text (for inputs)
+  role?: string;                 // ARIA role
+  required?: boolean;            // Is required field
+  context?: ElementContext;      // Additional context
+}
+
+/**
+ * Element Types
+ */
+export type ElementType =
+  | 'input'
+  | 'textarea'
+  | 'select'
+  | 'button'
+  | 'link'
+  | 'checkbox'
+  | 'radio'
+  | 'container'
+  | 'heading'
+  | 'text'
+  | 'image'
+  | 'list'
+  | 'unknown';
+
+/**
+ * Element Context
+ * Additional contextual information about an element
+ */
+export interface ElementContext {
+  component?: string;            // Component name where element was found
+  parentComponent?: string;      // Parent component name
+  depth?: number;                // Nesting depth from root
+  conditionalRendering?: boolean; // Is conditionally rendered
+  dynamicContent?: boolean;      // Contains dynamic content
+  props?: Record<string, any>;   // Component props (if available)
+}
+
+/**
+ * Scan Statistics
+ */
+export interface ScanStats {
+  totalComponents: number;       // Total components scanned
+  totalElements: number;         // Total elements found
+  maxDepth: number;              // Maximum depth reached
+  scanDuration: number;          // Scan duration in ms
+  filesScanned: number;          // Number of files scanned
+}
+
+/**
+ * Scanner Factory
+ * Creates appropriate scanner based on framework type
+ */
+export class ScannerFactory {
+  /**
+   * Create scanner instance for framework
+   */
+  static create(framework: 'react' | 'vue' | 'angular', config: RuntimeConfig): UIScanner {
+    switch (framework) {
+      case 'react':
+        // Dynamic import to avoid loading all scanners
+        const ReactScanner = require('./react-scanner').ReactScanner;
+        return new ReactScanner(config);
+
+      case 'vue':
+        throw new Error('Vue scanner not yet implemented');
+
+      case 'angular':
+        throw new Error('Angular scanner not yet implemented');
+
+      default:
+        throw new Error(`Unsupported framework: ${framework}`);
+    }
+  }
+}