mcp-maestro-mobile-ai 1.3.1 → 1.6.0

package/src/mcp-server/utils/promptAnalyzer.js

@@ -0,0 +1,701 @@
+/**
+ * Prompt Analyzer - Action-Element-Verification Model
+ * 
+ * This module analyzes user prompts to extract:
+ * - APP CONTEXT: Which app to test
+ * - ACTIONS: tap, input, scroll, swipe, select...
+ * - ELEMENTS: button, field, list, chart, table...
+ * - VALUES: credentials, data, selections...
+ * - VERIFICATIONS: visible, contains, count, state...
+ * - SEQUENCE: order of operations
+ * 
+ * It assesses completeness and determines whether to:
+ * - Generate YAML directly (complete prompt)
+ * - Ask clarifying questions (needs more info)
+ * - Generate with warnings (force generate with assumptions)
+ */
+
+/**
+ * Completeness levels for prompt analysis
+ */
+export const CompletenessLevel = {
+  COMPLETE: 'complete',           // All required info present, generate clean YAML
+  GENERATABLE: 'generatable',     // Missing some info, can generate with assumptions
+  NEEDS_CLARIFICATION: 'needs_clarification', // Missing important info, should ask
+  INSUFFICIENT: 'insufficient',   // Missing critical info (e.g., appId), cannot proceed
+};
+
+/**
+ * Action types that can be extracted from prompts
+ */
+export const ActionType = {
+  TAP: 'tap',
+  INPUT: 'input',
+  SCROLL: 'scroll',
+  SWIPE: 'swipe',
+  SELECT: 'select',
+  VERIFY: 'verify',
+  WAIT: 'wait',
+  NAVIGATE: 'navigate',
+  PRESS: 'press',
+  LONG_PRESS: 'long_press',
+  CLEAR: 'clear',
+  OPEN: 'open',
+  CLOSE: 'close',
+  SUBMIT: 'submit',
+};
+
+/**
+ * Element type indicators
+ */
+export const ElementType = {
+  BUTTON: 'button',
+  FIELD: 'field',
+  INPUT: 'input',
+  DROPDOWN: 'dropdown',
+  PICKER: 'picker',
+  LIST: 'list',
+  TABLE: 'table',
+  GRID: 'grid',
+  CHART: 'chart',
+  IMAGE: 'image',
+  CHECKBOX: 'checkbox',
+  RADIO: 'radio',
+  SWITCH: 'switch',
+  TOGGLE: 'toggle',
+  TAB: 'tab',
+  MENU: 'menu',
+  MODAL: 'modal',
+  DIALOG: 'dialog',
+  LINK: 'link',
+  ICON: 'icon',
+  TEXT: 'text',
+  LABEL: 'label',
+  HEADER: 'header',
+  CARD: 'card',
+  STEP: 'step',
+};
+
+/**
+ * Keywords that indicate specific actions
+ */
+const ACTION_KEYWORDS = {
+  tap: ['tap', 'click', 'press', 'touch', 'hit', 'select'],
+  input: ['enter', 'input', 'type', 'fill', 'write', 'set'],
+  scroll: ['scroll', 'swipe', 'slide'],
+  verify: ['verify', 'check', 'confirm', 'assert', 'see', 'visible', 'should see', 'display', 'displayed', 'shows', 'appear'],
+  navigate: ['go to', 'navigate', 'open', 'launch', 'switch to', 'move to'],
+  select: ['select', 'choose', 'pick', 'dropdown'],
+  submit: ['submit', 'send', 'sign in', 'log in', 'login', 'register', 'signup', 'sign up', 'save', 'confirm', 'proceed'],
+  wait: ['wait', 'loading', 'until'],
+  clear: ['clear', 'erase', 'delete', 'remove'],
+  search: ['search', 'find', 'look for', 'query'],
+};
+
+/**
+ * Keywords that indicate element types
+ */
+const ELEMENT_KEYWORDS = {
+  button: ['button', 'btn', 'submit', 'sign in', 'log in', 'login', 'register', 'save', 'confirm', 'cancel', 'ok', 'next', 'back', 'continue'],
+  field: ['field', 'input', 'textbox', 'text box', 'text field', 'entry', 'username', 'password', 'email', 'phone', 'name', 'address'],
+  dropdown: ['dropdown', 'drop down', 'select', 'picker', 'combo box', 'combobox', 'menu', 'region', 'country', 'state', 'category'],
+  list: ['list', 'items', 'results', 'options'],
+  table: ['table', 'grid', 'rows', 'columns', 'cells'],
+  chart: ['chart', 'graph', 'diagram', 'plot', 'visualization'],
+  checkbox: ['checkbox', 'check box', 'tick'],
+  radio: ['radio', 'radio button', 'option'],
+  switch: ['switch', 'toggle', 'on/off'],
+  tab: ['tab', 'tabs'],
+  modal: ['modal', 'dialog', 'popup', 'pop-up', 'alert', 'overlay'],
+  image: ['image', 'photo', 'picture', 'icon', 'avatar'],
+  link: ['link', 'hyperlink', 'url'],
+  step: ['step', 'stage', 'wizard', 'progress'],
+  card: ['card', 'tile', 'panel'],
+};
+
+/**
+ * Verification keywords
+ */
+const VERIFICATION_KEYWORDS = {
+  visible: ['visible', 'displayed', 'shown', 'appears', 'can see', 'should see', 'see the'],
+  contains: ['contains', 'has', 'includes', 'shows', 'displays'],
+  count: ['count', 'number of', 'total', 'how many'],
+  state: ['enabled', 'disabled', 'active', 'inactive', 'checked', 'unchecked', 'selected'],
+  text: ['text', 'message', 'label', 'title', 'content'],
+  success: ['success', 'successful', 'passed', 'complete', 'done', 'logged in', 'registered'],
+  error: ['error', 'failed', 'failure', 'invalid', 'wrong', 'incorrect'],
+};
+
+/**
+ * App ID patterns
+ */
+const APP_ID_PATTERNS = [
+  /(?:app\s*(?:id)?|package|bundle)\s*[:=]?\s*([a-zA-Z][a-zA-Z0-9_]*(?:\.[a-zA-Z][a-zA-Z0-9_]*)+)/i,
+  /\b([a-zA-Z][a-zA-Z0-9_]*(?:\.[a-zA-Z][a-zA-Z0-9_]*){2,})\b/,
+];
+
+/**
+ * Value extraction patterns
+ */
+const VALUE_PATTERNS = {
+  quoted: /["']([^"']+)["']/g,
+  colon: /:\s*([^\s,]+)/g,
+  equals: /=\s*([^\s,]+)/g,
+  withLabel: /(?:username|user|email|password|pass|phone|name|value)[\s:=]+["']?([^"'\s,]+)["']?/gi,
+};
+
+/**
+ * Analyze a user prompt and extract structured information
+ * 
+ * @param {string} userPrompt - The user's test description
+ * @param {object} options - Additional context (appId, etc.)
+ * @returns {object} Analysis result with extracted info and completeness assessment
+ */
+export function analyzePrompt(userPrompt, options = {}) {
+  const prompt = userPrompt.trim().toLowerCase();
+  const originalPrompt = userPrompt.trim();
+  
+  // Extract all components
+  const appContext = extractAppContext(originalPrompt, options.appId);
+  const actions = extractActions(originalPrompt);
+  const elements = extractElements(originalPrompt);
+  const values = extractValues(originalPrompt);
+  const verifications = extractVerifications(originalPrompt);
+  const sequence = buildSequence(actions, elements, values, verifications);
+  
+  // Assess completeness
+  const assessment = assessCompleteness({
+    appContext,
+    actions,
+    elements,
+    values,
+    verifications,
+    sequence,
+  });
+  
+  return {
+    extracted: {
+      appContext,
+      actions,
+      elements,
+      values,
+      verifications,
+      sequence,
+    },
+    assessment,
+    originalPrompt,
+  };
+}
+
+/**
+ * Extract app context from prompt
+ */
+function extractAppContext(prompt, providedAppId = null) {
+  if (providedAppId) {
+    return {
+      appId: providedAppId,
+      source: 'provided',
+    };
+  }
+  
+  // Try to find app ID in prompt
+  for (const pattern of APP_ID_PATTERNS) {
+    const match = prompt.match(pattern);
+    if (match && match[1]) {
+      return {
+        appId: match[1],
+        source: 'extracted',
+      };
+    }
+  }
+  
+  // Try to find app name mentions
+  const appNamePatterns = [
+    /(?:on|in|for|app|application)\s+["']?([A-Z][a-zA-Z0-9\s]+)["']?/i,
+    /^test\s+(?:that\s+)?(?:the\s+)?["']?([A-Z][a-zA-Z0-9\s]+)["']?\s+app/i,
+  ];
+  
+  for (const pattern of appNamePatterns) {
+    const match = prompt.match(pattern);
+    if (match && match[1]) {
+      return {
+        appName: match[1].trim(),
+        appId: null,
+        source: 'extracted_name',
+      };
+    }
+  }
+  
+  return {
+    appId: null,
+    source: 'missing',
+  };
+}
+
+/**
+ * Extract actions from prompt
+ */
+function extractActions(prompt) {
+  const actions = [];
+  const promptLower = prompt.toLowerCase();
+  
+  for (const [actionType, keywords] of Object.entries(ACTION_KEYWORDS)) {
+    for (const keyword of keywords) {
+      const regex = new RegExp(`\\b${keyword}\\b`, 'gi');
+      let match;
+      while ((match = regex.exec(promptLower)) !== null) {
+        actions.push({
+          type: actionType.toUpperCase(),
+          keyword: keyword,
+          position: match.index,
+          context: prompt.substring(Math.max(0, match.index - 20), match.index + 50),
+        });
+      }
+    }
+  }
+  
+  // Sort by position and deduplicate nearby actions
+  actions.sort((a, b) => a.position - b.position);
+  
+  // Remove duplicates that are too close together (same type within 20 chars)
+  const dedupedActions = [];
+  for (const action of actions) {
+    const isDuplicate = dedupedActions.some(
+      existing => existing.type === action.type && 
+                  Math.abs(existing.position - action.position) < 20
+    );
+    if (!isDuplicate) {
+      dedupedActions.push(action);
+    }
+  }
+  
+  return dedupedActions;
+}
+
+/**
+ * Extract elements from prompt
+ */
+function extractElements(prompt) {
+  const elements = [];
+  const promptLower = prompt.toLowerCase();
+  
+  for (const [elementType, keywords] of Object.entries(ELEMENT_KEYWORDS)) {
+    for (const keyword of keywords) {
+      const regex = new RegExp(`\\b${keyword}\\b`, 'gi');
+      let match;
+      while ((match = regex.exec(promptLower)) !== null) {
+        // Try to extract the element name/label
+        const context = prompt.substring(Math.max(0, match.index - 30), match.index + keyword.length + 50);
+        const labelMatch = context.match(/["']([^"']+)["']/) || 
+                          context.match(/(?:the|a|an)\s+(\w+(?:\s+\w+)?)\s+\w+/);
+        
+        elements.push({
+          type: elementType.toUpperCase(),
+          keyword: keyword,
+          position: match.index,
+          label: labelMatch ? labelMatch[1] : null,
+          context: context.trim(),
+        });
+      }
+    }
+  }
+  
+  // Deduplicate
+  const seen = new Set();
+  return elements.filter(el => {
+    const key = `${el.type}-${el.position}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+/**
+ * Extract values from prompt
+ */
+function extractValues(prompt) {
+  const values = {};
+  
+  // Extract quoted values
+  const quotedMatches = [...prompt.matchAll(/["']([^"']+)["']/g)];
+  quotedMatches.forEach((match, idx) => {
+    values[`quoted_${idx}`] = match[1];
+  });
+  
+  // Extract labeled values (username: xyz, password: abc)
+  const labelPatterns = [
+    { pattern: /username[\s:=]+["']?([^"'\s,]+)["']?/gi, field: 'username' },
+    { pattern: /user[\s:=]+["']?([^"'\s,]+)["']?/gi, field: 'username' },
+    { pattern: /email[\s:=]+["']?([^"'\s,]+)["']?/gi, field: 'email' },
+    { pattern: /password[\s:=]+["']?([^"'\s,]+)["']?/gi, field: 'password' },
+    { pattern: /pass[\s:=]+["']?([^"'\s,]+)["']?/gi, field: 'password' },
+    { pattern: /phone[\s:=]+["']?([^"'\s,]+)["']?/gi, field: 'phone' },
+    { pattern: /name[\s:=]+["']?([^"'\s,]+)["']?/gi, field: 'name' },
+    { pattern: /region[\s:=]+["']?([^"'\s,]+)["']?/gi, field: 'region' },
+    { pattern: /country[\s:=]+["']?([^"'\s,]+)["']?/gi, field: 'country' },
+    { pattern: /search[\s:=]+["']?([^"'\s,]+)["']?/gi, field: 'search' },
+    { pattern: /query[\s:=]+["']?([^"'\s,]+)["']?/gi, field: 'search' },
+  ];
+  
+  for (const { pattern, field } of labelPatterns) {
+    const matches = [...prompt.matchAll(pattern)];
+    if (matches.length > 0) {
+      values[field] = matches[matches.length - 1][1]; // Take last match
+    }
+  }
+  
+  // Extract with/using patterns (e.g., "with username abc")
+  const withPattern = /with\s+(\w+)\s+["']?([^"'\s,]+)["']?/gi;
+  const withMatches = [...prompt.matchAll(withPattern)];
+  for (const match of withMatches) {
+    values[match[1].toLowerCase()] = match[2];
+  }
+  
+  return values;
+}
+
+/**
+ * Extract verifications from prompt
+ */
+function extractVerifications(prompt) {
+  const verifications = [];
+  const promptLower = prompt.toLowerCase();
+  
+  for (const [verificationType, keywords] of Object.entries(VERIFICATION_KEYWORDS)) {
+    for (const keyword of keywords) {
+      const regex = new RegExp(`\\b${keyword}\\b`, 'gi');
+      let match;
+      while ((match = regex.exec(promptLower)) !== null) {
+        // Extract what should be verified
+        const afterKeyword = prompt.substring(match.index + keyword.length, match.index + keyword.length + 100);
+        const targetMatch = afterKeyword.match(/\s*["']?([^"'\n,]+?)["']?\s*(?:$|,|and|\.)/);
+        
+        verifications.push({
+          type: verificationType.toUpperCase(),
+          keyword: keyword,
+          target: targetMatch ? targetMatch[1].trim() : null,
+          position: match.index,
+        });
+      }
+    }
+  }
+  
+  return verifications;
+}
+
+/**
+ * Build action sequence from extracted components
+ */
+function buildSequence(actions, elements, values, verifications) {
+  const sequence = [];
+  const allItems = [
+    ...actions.map(a => ({ ...a, category: 'action' })),
+    ...elements.map(e => ({ ...e, category: 'element' })),
+    ...verifications.map(v => ({ ...v, category: 'verification' })),
+  ];
+  
+  // Sort by position
+  allItems.sort((a, b) => a.position - b.position);
+  
+  // Build logical sequence
+  for (let i = 0; i < allItems.length; i++) {
+    const item = allItems[i];
+    
+    if (item.category === 'action') {
+      // Find associated element
+      const nextElement = allItems.find(
+        (x, j) => j > i && x.category === 'element' && x.position - item.position < 50
+      );
+      
+      sequence.push({
+        action: item.type,
+        element: nextElement ? nextElement.label || nextElement.keyword : null,
+        elementType: nextElement ? nextElement.type : null,
+        value: findValueForAction(item, values),
+      });
+    } else if (item.category === 'verification' && !sequence.some(s => s.action === 'VERIFY' && s.target === item.target)) {
+      sequence.push({
+        action: 'VERIFY',
+        type: item.type,
+        target: item.target,
+      });
+    }
+  }
+  
+  return sequence;
+}
+
+/**
+ * Find value associated with an action
+ */
+function findValueForAction(action, values) {
+  const context = action.context.toLowerCase();
+  
+  // Check for common field-value associations
+  if (context.includes('username') || context.includes('user')) {
+    return values.username || values.user || null;
+  }
+  if (context.includes('password') || context.includes('pass')) {
+    return values.password || values.pass || null;
+  }
+  if (context.includes('email')) {
+    return values.email || null;
+  }
+  if (context.includes('search') || context.includes('query')) {
+    return values.search || values.query || null;
+  }
+  
+  return null;
+}
+
+/**
+ * Assess completeness of extracted information
+ */
+function assessCompleteness(extracted) {
+  const { appContext, actions, elements, values, verifications, sequence } = extracted;
+  
+  const issues = [];
+  const missing = [];
+  const assumptions = [];
+  let score = 100;
+  
+  // Critical: App context
+  if (!appContext.appId) {
+    if (appContext.appName) {
+      issues.push('App ID not found (only app name detected)');
+      assumptions.push(`Will need app ID for: ${appContext.appName}`);
+      score -= 40;
+    } else {
+      issues.push('No app identifier found');
+      missing.push('appId');
+      score -= 50;
+    }
+  }
+  
+  // Important: Actions
+  if (actions.length === 0) {
+    issues.push('No actions detected in prompt');
+    missing.push('actions');
+    score -= 20;
+  }
+  
+  // Important: Elements
+  if (elements.length === 0 && actions.length > 0) {
+    issues.push('Actions found but no target elements identified');
+    assumptions.push('Will use common element patterns based on action types');
+    score -= 15;
+  }
+  
+  // Useful: Values for input actions
+  const inputActions = actions.filter(a => a.type === 'INPUT');
+  if (inputActions.length > 0 && Object.keys(values).length === 0) {
+    issues.push('Input actions detected but no values provided');
+    missing.push('input_values');
+    score -= 15;
+  }
+  
+  // Useful: Verifications
+  if (verifications.length === 0) {
+    assumptions.push('No explicit verification - will add generic success check');
+    score -= 5;
+  }
+  
+  // Check for element labels
+  const unlabeledElements = elements.filter(e => !e.label);
+  if (unlabeledElements.length > 0) {
+    assumptions.push(`${unlabeledElements.length} element(s) without explicit labels - will use common patterns`);
+    score -= unlabeledElements.length * 3;
+  }
+  
+  // Determine completeness level
+  let level;
+  if (score >= 80 && appContext.appId && actions.length > 0) {
+    level = CompletenessLevel.COMPLETE;
+  } else if (score >= 50 && appContext.appId) {
+    level = CompletenessLevel.GENERATABLE;
+  } else if (appContext.appId) {
+    level = CompletenessLevel.NEEDS_CLARIFICATION;
+  } else {
+    level = CompletenessLevel.INSUFFICIENT;
+  }
+  
+  return {
+    level,
+    score: Math.max(0, score),
+    issues,
+    missing,
+    assumptions,
+    canForceGenerate: level !== CompletenessLevel.INSUFFICIENT,
+    hasAppId: !!appContext.appId,
+    hasActions: actions.length > 0,
+    hasElements: elements.length > 0,
+    hasValues: Object.keys(values).length > 0,
+    hasVerifications: verifications.length > 0,
+  };
+}
+
+/**
+ * Generate clarification questions based on analysis
+ */
+export function generateClarificationQuestions(analysis) {
+  const { extracted, assessment } = analysis;
+  const questions = [];
+  
+  // Critical questions (blocking)
+  if (!extracted.appContext.appId) {
+    questions.push({
+      priority: 'critical',
+      field: 'appId',
+      question: 'Which app should be tested? Please provide the package ID (e.g., com.example.app)',
+      required: true,
+    });
+  }
+  
+  // Important questions (improve quality)
+  if (assessment.missing.includes('actions')) {
+    questions.push({
+      priority: 'important',
+      field: 'actions',
+      question: 'What actions should the test perform? (e.g., tap, enter text, scroll)',
+      required: false,
+    });
+  }
+  
+  // Element labeling questions
+  const inputActions = extracted.actions.filter(a => a.type === 'INPUT');
+  if (inputActions.length > 0) {
+    // Ask about field labels
+    if (!extracted.values.username && inputActions.some(a => a.context.includes('user') || a.context.includes('email'))) {
+      questions.push({
+        priority: 'recommended',
+        field: 'usernameLabel',
+        question: 'What is the label/placeholder for the username/email field?',
+        required: false,
+        default: 'Username',
+      });
+    }
+    
+    if (!extracted.values.password && inputActions.some(a => a.context.includes('password') || a.context.includes('pass'))) {
+      questions.push({
+        priority: 'recommended',
+        field: 'passwordLabel',
+        question: 'What is the label/placeholder for the password field?',
+        required: false,
+        default: 'Password',
+      });
+    }
+  }
+  
+  // Submit button question
+  const submitActions = extracted.actions.filter(a => a.type === 'SUBMIT');
+  if (submitActions.length > 0) {
+    questions.push({
+      priority: 'recommended',
+      field: 'submitButtonLabel',
+      question: 'What is the text on the submit/login button?',
+      required: false,
+      default: 'Sign In',
+    });
+  }
+  
+  // Verification question
+  if (extracted.verifications.length === 0) {
+    questions.push({
+      priority: 'recommended',
+      field: 'successIndicator',
+      question: 'What element confirms successful completion? (e.g., welcome message, dashboard)',
+      required: false,
+      default: null,
+    });
+  }
+  
+  // Dropdown/select questions
+  const dropdownElements = extracted.elements.filter(e => e.type === 'DROPDOWN');
+  for (const dropdown of dropdownElements) {
+    questions.push({
+      priority: 'recommended',
+      field: `dropdown_${dropdown.keyword}`,
+      question: `For the ${dropdown.keyword} dropdown: What is the current value shown? What value should be selected?`,
+      required: false,
+    });
+  }
+  
+  return questions;
+}
+
+/**
+ * Generate warnings for force-generated YAML
+ */
+export function generateWarnings(analysis) {
+  const { assessment } = analysis;
+  const warnings = [];
+  
+  for (const assumption of assessment.assumptions) {
+    warnings.push({
+      type: 'assumption',
+      message: assumption,
+    });
+  }
+  
+  if (assessment.missing.includes('input_values')) {
+    warnings.push({
+      type: 'missing_data',
+      message: 'Input values not specified - placeholders will be used',
+    });
+  }
+  
+  if (!assessment.hasVerifications) {
+    warnings.push({
+      type: 'no_verification',
+      message: 'No success verification specified - test may pass without confirming expected outcome',
+    });
+  }
+  
+  return warnings;
+}
+
+/**
+ * Get default assumptions for common test patterns
+ */
+export function getDefaultAssumptions(analysis) {
+  const { extracted } = analysis;
+  const defaults = {};
+  
+  // Default element labels based on detected patterns
+  const hasLogin = extracted.actions.some(a => 
+    ['login', 'sign in', 'log in'].some(k => a.context.toLowerCase().includes(k))
+  );
+  
+  if (hasLogin) {
+    defaults.usernameField = 'Username';
+    defaults.passwordField = 'Password';
+    defaults.submitButton = 'Sign In';
+    defaults.alternatives = {
+      usernameField: ['Email', 'User ID', 'Login'],
+      passwordField: ['Password', 'Pass'],
+      submitButton: ['Sign In', 'Login', 'Log In', 'Submit'],
+    };
+  }
+  
+  // Search pattern
+  const hasSearch = extracted.actions.some(a => a.type === 'SEARCH');
+  if (hasSearch) {
+    defaults.searchField = 'Search';
+    defaults.alternatives = {
+      searchField: ['Search', 'Search...', 'Find'],
+    };
+  }
+  
+  return defaults;
+}
+
+export default {
+  CompletenessLevel,
+  ActionType,
+  ElementType,
+  analyzePrompt,
+  generateClarificationQuestions,
+  generateWarnings,
+  getDefaultAssumptions,
+};
+