@sun-asterisk/sungen 1.0.0

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

@@ -0,0 +1,629 @@
+/**
+ * Strict UI Scanner - v3.1
+ *
+ * Priority-based, deterministic scanner with strict filtering
+ *
+ * Key Principles:
+ * 1. Only scan INTERACTIVE elements (input, button, a, select, textarea)
+ * 2. Only include elements with data-testid OR role attributes
+ * 3. Discard generic containers (div, span) unless they have id
+ * 4. 80-90% noise reduction vs deep scanner
+ *
+ * Philosophy: AI is a fallback, not the primary solution
+ */
+
+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';
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export interface StrictScanConfig {
+  sourceRoot: string;
+  projectRoot: string;
+  strictMode: boolean;
+  filterRules: {
+    allowedTags: string[];
+    requireAttributes: string[];
+    allowGenericWithId: boolean;
+  };
+  verbose?: boolean;
+}
+
+export interface StrictUIElement {
+  // Flat, locator-centric schema
+  logicalName: string;           // e.g., "email-input"
+  primaryLocator: string;         // e.g., "[data-testid='login-email']"
+  fallbackStrategy: string;       // e.g., "role=textbox[name='email']"
+
+  // Metadata
+  tag: string;                    // e.g., "input"
+  elementType: string;            // e.g., "email", "button", "link"
+
+  // Discovery info
+  discoveryMethod: 'direct-id' | 'accessibility' | 'heuristic';
+  confidence: 'high' | 'medium' | 'low';
+
+  // Source tracking
+  sourceFile: string;
+
+  // Optional attributes
+  label?: string;
+  placeholder?: string;
+  ariaLabel?: string;
+  role?: string;
+  text?: string;
+
+  // Raw props for reference
+  props: Record<string, any>;
+}
+
+export interface StrictScanResult {
+  screen: string;
+  timestamp: number;
+  framework: string;
+  sourceFiles: string[];
+  elements: StrictUIElement[];
+  stats: {
+    totalScanned: number;
+    totalFiltered: number;
+    totalIncluded: number;
+    filterRate: number;
+    directIdMatches: number;
+    accessibilityMatches: number;
+    heuristicMatches: number;
+    scanDuration: number;
+  };
+}
+
+// ============================================================================
+// STRICT FILTER
+// ============================================================================
+
+class StrictElementFilter {
+  private config: StrictScanConfig;
+
+  constructor(config: StrictScanConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Determine if element should be included in scan results
+   *
+   * Priority filtering:
+   * 1. Interactive tags (input, button, a, select, textarea)
+   * 2. Elements with data-testid or role
+   * 3. Generic containers (div, span) ONLY if they have id
+   */
+  shouldInclude(element: any): boolean {
+    const tag = element.tag?.toLowerCase();
+    const props = element.props || {};
+
+    // Priority 1: Interactive elements
+    const interactiveTags = this.config.filterRules.allowedTags;
+    if (interactiveTags.includes(tag)) {
+      return true;
+    }
+
+    // Priority 2: Elements with required attributes (data-testid or role)
+    const hasRequiredAttr = this.config.filterRules.requireAttributes.some(
+      attr => props[attr] !== undefined && props[attr] !== null
+    );
+    if (hasRequiredAttr) {
+      return true;
+    }
+
+    // Priority 3: Generic containers with ID
+    if (this.config.filterRules.allowGenericWithId) {
+      const genericTags = ['div', 'span'];
+      if (genericTags.includes(tag) && props.id) {
+        return true;
+      }
+    }
+
+    // Filter out everything else
+    return false;
+  }
+
+  /**
+   * Get filter reason for logging/debugging
+   */
+  getFilterReason(element: any): string {
+    const tag = element.tag?.toLowerCase();
+    const props = element.props || {};
+
+    if (this.config.filterRules.allowedTags.includes(tag)) {
+      return 'interactive-tag';
+    }
+
+    const hasRequiredAttr = this.config.filterRules.requireAttributes.some(
+      attr => props[attr] !== undefined
+    );
+    if (hasRequiredAttr) {
+      return 'has-required-attribute';
+    }
+
+    if (['div', 'span'].includes(tag) && props.id) {
+      return 'generic-with-id';
+    }
+
+    return 'filtered-out';
+  }
+}
+
+// ============================================================================
+// LOGICAL NAME GENERATOR
+// ============================================================================
+
+class LogicalNameGenerator {
+  /**
+   * Generate logical, human-readable name for element
+   *
+   * Examples:
+   * - input[type=email] → "email-input"
+   * - button[type=submit] → "submit-btn"
+   * - a[href="/login"] → "login-link"
+   */
+  generate(element: any, index: number): string {
+    const tag = element.tag?.toLowerCase();
+    const props = element.props || {};
+
+    let name = '';
+
+    // Use data-testid if available (most stable)
+    if (props['data-testid']) {
+      return this.cleanName(props['data-testid']);
+    }
+
+    // Use name attribute
+    if (props.name) {
+      name = props.name;
+    }
+    // Use id attribute
+    else if (props.id) {
+      name = props.id;
+    }
+    // Use aria-label
+    else if (props['aria-label']) {
+      name = props['aria-label'];
+    }
+    // Use placeholder for inputs
+    else if (props.placeholder && tag === 'input') {
+      name = props.placeholder;
+    }
+    // Use text content for buttons/links
+    else if (element.text && ['button', 'a'].includes(tag)) {
+      name = element.text;
+    }
+    // Use type for inputs
+    else if (props.type && tag === 'input') {
+      name = props.type;
+    }
+    // Fallback to tag + index
+    else {
+      name = `${tag}-${index}`;
+    }
+
+    // Add suffix based on tag
+    const suffix = this.getSuffix(tag);
+
+    return this.cleanName(name) + suffix;
+  }
+
+  private getSuffix(tag: string): string {
+    const suffixMap: Record<string, string> = {
+      'input': '-input',
+      'textarea': '-textarea',
+      'select': '-select',
+      'button': '-btn',
+      'a': '-link',
+    };
+
+    return suffixMap[tag] || '';
+  }
+
+  private cleanName(name: string): string {
+    return name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '');
+  }
+}
+
+// ============================================================================
+// LOCATOR GENERATOR
+// ============================================================================
+
+class LocatorGenerator {
+  /**
+   * Generate primary locator (Playwright-compatible)
+   *
+   * Priority:
+   * 1. data-testid (most stable)
+   * 2. role + aria-label (semantic)
+   * 3. id attribute
+   * 4. name attribute
+   * 5. type + other attributes
+   */
+  generatePrimary(element: any): { locator: string; method: string; confidence: string } {
+    const tag = element.tag?.toLowerCase();
+    const props = element.props || {};
+
+    // Priority 1: data-testid (BEST - deterministic, stable)
+    if (props['data-testid']) {
+      return {
+        locator: `[data-testid="${props['data-testid']}"]`,
+        method: 'direct-id',
+        confidence: 'high',
+      };
+    }
+
+    // Priority 2: role + aria-label (GOOD - semantic, accessible)
+    if (props.role && props['aria-label']) {
+      return {
+        locator: `[role="${props.role}"][aria-label="${props['aria-label']}"]`,
+        method: 'accessibility',
+        confidence: 'high',
+      };
+    }
+
+    // Priority 2b: role only
+    if (props.role) {
+      return {
+        locator: `[role="${props.role}"]`,
+        method: 'accessibility',
+        confidence: 'medium',
+      };
+    }
+
+    // Priority 3: id attribute (OKAY - might change)
+    if (props.id) {
+      return {
+        locator: `#${props.id}`,
+        method: 'heuristic',
+        confidence: 'medium',
+      };
+    }
+
+    // Priority 4: name attribute (for form fields)
+    if (props.name && ['input', 'select', 'textarea'].includes(tag)) {
+      return {
+        locator: `${tag}[name="${props.name}"]`,
+        method: 'heuristic',
+        confidence: 'medium',
+      };
+    }
+
+    // Priority 5: type + placeholder (for inputs)
+    if (tag === 'input' && props.type && props.placeholder) {
+      return {
+        locator: `input[type="${props.type}"][placeholder="${props.placeholder}"]`,
+        method: 'heuristic',
+        confidence: 'low',
+      };
+    }
+
+    // Priority 6: tag + type
+    if (props.type) {
+      return {
+        locator: `${tag}[type="${props.type}"]`,
+        method: 'heuristic',
+        confidence: 'low',
+      };
+    }
+
+    // Fallback: tag only (WEAK)
+    return {
+      locator: tag,
+      method: 'heuristic',
+      confidence: 'low',
+    };
+  }
+
+  /**
+   * Generate fallback strategy (when primary fails)
+   */
+  generateFallback(element: any): string {
+    const tag = element.tag?.toLowerCase();
+    const props = element.props || {};
+
+    const strategies: string[] = [];
+
+    // Strategy 1: Text content
+    if (element.text && ['button', 'a'].includes(tag)) {
+      strategies.push(`${tag}:has-text("${element.text}")`);
+    }
+
+    // Strategy 2: Placeholder
+    if (props.placeholder) {
+      strategies.push(`${tag}[placeholder="${props.placeholder}"]`);
+    }
+
+    // Strategy 3: Name
+    if (props.name) {
+      strategies.push(`${tag}[name="${props.name}"]`);
+    }
+
+    // Strategy 4: Type
+    if (props.type) {
+      strategies.push(`${tag}[type="${props.type}"]`);
+    }
+
+    // Return first strategy or tag as ultimate fallback
+    return strategies.length > 0 ? strategies[0] : tag;
+  }
+}
+
+// ============================================================================
+// STRICT SCANNER
+// ============================================================================
+
+export class StrictScanner {
+  private config: StrictScanConfig;
+  private filter: StrictElementFilter;
+  private nameGenerator: LogicalNameGenerator;
+  private locatorGenerator: LocatorGenerator;
+
+  private elements: StrictUIElement[] = [];
+  private scannedFiles = new Set<string>();
+  private stats = {
+    totalScanned: 0,
+    totalFiltered: 0,
+    totalIncluded: 0,
+    directIdMatches: 0,
+    accessibilityMatches: 0,
+    heuristicMatches: 0,
+  };
+
+  constructor(config: StrictScanConfig) {
+    this.config = config;
+    this.filter = new StrictElementFilter(config);
+    this.nameGenerator = new LogicalNameGenerator();
+    this.locatorGenerator = new LocatorGenerator();
+  }
+
+  /**
+   * Scan a screen and generate strict UI model
+   */
+  async scan(screenName: string): Promise<StrictScanResult> {
+    const startTime = Date.now();
+
+    // Find entry file for screen
+    const entryFile = this.findEntryFile(screenName);
+    if (!entryFile) {
+      throw new Error(`Entry file not found for screen: ${screenName}`);
+    }
+
+    // Scan recursively
+    await this.scanFile(entryFile);
+
+    const duration = Date.now() - startTime;
+
+    return {
+      screen: screenName,
+      timestamp: Date.now(),
+      framework: 'react',
+      sourceFiles: Array.from(this.scannedFiles),
+      elements: this.elements,
+      stats: {
+        ...this.stats,
+        filterRate: this.stats.totalScanned > 0
+          ? (this.stats.totalFiltered / this.stats.totalScanned) * 100
+          : 0,
+        scanDuration: duration,
+      },
+    };
+  }
+
+  private findEntryFile(screenName: string): string | null {
+    // Convert screen name to path: auth-login -> auth/login
+    const screenPath = screenName.replace(/-/g, '/');
+
+    // Try common patterns
+    const patterns = [
+      `${screenPath}/page.tsx`,
+      `${screenPath}/index.tsx`,
+      `${screenPath}.tsx`,
+      `${screenPath}/page.js`,
+      `${screenPath}/index.js`,
+      `${screenPath}.js`,
+    ];
+
+    for (const pattern of patterns) {
+      const filePath = path.join(this.config.sourceRoot, pattern);
+      if (fs.existsSync(filePath)) {
+        return filePath;
+      }
+    }
+
+    return null;
+  }
+
+  private async scanFile(filePath: string): Promise<void> {
+    // Avoid re-scanning
+    if (this.scannedFiles.has(filePath)) {
+      return;
+    }
+
+    this.scannedFiles.add(filePath);
+
+    // Read file
+    const code = fs.readFileSync(filePath, 'utf-8');
+
+    // Parse with Babel
+    const ast = parser.parse(code, {
+      sourceType: 'module',
+      plugins: ['jsx', 'typescript'],
+    });
+
+    // Traverse AST and extract elements
+    traverse(ast, {
+      JSXElement: (path) => {
+        this.processJSXElement(path.node, filePath);
+      },
+    });
+  }
+
+  private processJSXElement(node: any, sourceFile: string): void {
+    const element = this.extractElementData(node);
+
+    this.stats.totalScanned++;
+
+    // Apply strict filter
+    if (!this.filter.shouldInclude(element)) {
+      this.stats.totalFiltered++;
+
+      if (this.config.verbose) {
+        const reason = this.filter.getFilterReason(element);
+        console.log(`[FILTERED] ${element.tag} - ${reason}`);
+      }
+
+      return;
+    }
+
+    // Element passed filter - process it
+    this.stats.totalIncluded++;
+
+    const strictElement = this.buildStrictElement(element, sourceFile);
+    this.elements.push(strictElement);
+
+    // Update discovery stats
+    if (strictElement.discoveryMethod === 'direct-id') {
+      this.stats.directIdMatches++;
+    } else if (strictElement.discoveryMethod === 'accessibility') {
+      this.stats.accessibilityMatches++;
+    } else {
+      this.stats.heuristicMatches++;
+    }
+
+    if (this.config.verbose) {
+      console.log(
+        `[INCLUDED] ${strictElement.logicalName} - ${strictElement.discoveryMethod} (${strictElement.confidence})`
+      );
+    }
+  }
+
+  private extractElementData(node: any): any {
+    // Extract tag name
+    const openingElement = node.openingElement;
+    const tag = this.getTagName(openingElement.name);
+
+    // Extract props
+    const props: Record<string, any> = {};
+    for (const attr of openingElement.attributes || []) {
+      if (t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name)) {
+        const name = attr.name.name;
+        const value = this.getAttributeValue(attr.value);
+        props[name] = value;
+      }
+    }
+
+    // Extract text content
+    const text = this.extractTextContent(node);
+
+    return { tag, props, text };
+  }
+
+  private getTagName(name: any): string {
+    if (t.isJSXIdentifier(name)) {
+      return name.name;
+    }
+    if (t.isJSXMemberExpression(name)) {
+      // Handle <Form.Input> → "input"
+      return this.getTagName(name.property);
+    }
+    return 'unknown';
+  }
+
+  private getAttributeValue(value: any): any {
+    if (!value) return true; // Boolean attribute
+    if (t.isStringLiteral(value)) return value.value;
+    if (t.isJSXExpressionContainer(value)) {
+      if (t.isStringLiteral(value.expression)) {
+        return value.expression.value;
+      }
+      if (t.isBooleanLiteral(value.expression)) {
+        return value.expression.value;
+      }
+      if (t.isNumericLiteral(value.expression)) {
+        return value.expression.value;
+      }
+    }
+    return undefined;
+  }
+
+  private extractTextContent(node: any): string | null {
+    const children = node.children || [];
+
+    for (const child of children) {
+      if (t.isJSXText(child)) {
+        const text = child.value.trim();
+        if (text) return text;
+      }
+      if (t.isJSXExpressionContainer(child)) {
+        if (t.isStringLiteral(child.expression)) {
+          return child.expression.value;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  private buildStrictElement(element: any, sourceFile: string): StrictUIElement {
+    // Generate logical name
+    const logicalName = this.nameGenerator.generate(element, this.elements.length);
+
+    // Generate locators
+    const primary = this.locatorGenerator.generatePrimary(element);
+    const fallback = this.locatorGenerator.generateFallback(element);
+
+    // Determine element type
+    const elementType = this.inferElementType(element);
+
+    return {
+      logicalName,
+      primaryLocator: primary.locator,
+      fallbackStrategy: fallback,
+
+      tag: element.tag,
+      elementType,
+
+      discoveryMethod: primary.method as any,
+      confidence: primary.confidence as any,
+
+      sourceFile,
+
+      label: element.props.label,
+      placeholder: element.props.placeholder,
+      ariaLabel: element.props['aria-label'],
+      role: element.props.role,
+      text: element.text,
+
+      props: element.props,
+    };
+  }
+
+  private inferElementType(element: any): string {
+    const tag = element.tag?.toLowerCase();
+    const props = element.props || {};
+
+    if (tag === 'input' && props.type) {
+      return props.type; // email, password, text, etc.
+    }
+
+    if (tag === 'button') {
+      return props.type || 'button';
+    }
+
+    if (tag === 'a') {
+      return 'link';
+    }
+
+    return tag;
+  }
+}