qaa-agent 1.9.1 → 1.9.5

package/bin/lib/intent-detector.cjs

@@ -0,0 +1,488 @@
+/**
+ * Intent Detector — Natural Language argument parser for QAA commands.
+ *
+ * Detects URLs, paths (with spaces, quoted, Windows/Unix), framework hints,
+ * tickets vs AUT URLs, code-repo URLs (GitHub/GitLab/Bitbucket), and parses
+ * --flag values robustly. Also infers semantic roles (dev-repo vs qa-repo,
+ * app-url) from NL context markers.
+ *
+ * Used by /qa-start, /qa-create-test, /qa-fix, /qa-audit, /qa-pr to support
+ * natural-language input alongside explicit flags. Flags always take
+ * precedence; NL detection only fills gaps.
+ */
+
+'use strict';
+
+// ── Patterns ──────────────────────────────────────────────────────────────
+
+const URL_PATTERN = /https?:\/\/[^\s'"<>`]+/gi;
+const WIN_PATH_PATTERN = /[A-Z]:[\\\/](?:[^\n\r"<>|*?]+)/g;
+const UNIX_PATH_PATTERN = /(?:^|(?<=[\s=]))(\/[a-zA-Z0-9_][a-zA-Z0-9._\-]*(?:\/[a-zA-Z0-9._\-]+)+\/?)/g;
+const QUOTED_PATTERN = /"([^"]+)"|'([^']+)'/g;
+
+const FRAMEWORK_PATTERNS = [
+  ['robot-framework', /\b(?:robot[\s-]*framework|robotframework)\b/i],
+  ['playwright', /\bplaywright\b/i],
+  ['cypress', /\bcypress\b/i],
+  ['vitest', /\bvitest\b/i],
+  ['pytest', /\bpytest\b/i],
+  ['selenium', /\bselenium\b/i],
+  ['jest', /\bjest\b/i],
+];
+
+const TICKET_PATTERNS = [
+  /github\.com\/[\w.-]+\/[\w.-]+\/(?:issues|pull)\//i,
+  /atlassian\.net\/browse\//i,
+  /linear\.app\//i,
+  /dev\.azure\.com|visualstudio\.com/i,
+];
+
+// Code repo URLs (NOT AUT). Checked AFTER tickets, so issue/PR URLs match tickets first.
+const CODE_REPO_PATTERNS = [
+  /^https?:\/\/github\.com\/[\w.-]+\/[\w.-]+\/?($|[?#])/i,
+  /^https?:\/\/github\.com\/[\w.-]+\/[\w.-]+\/(?:tree|blob|raw|releases|tags|commits?|wiki)/i,
+  /^https?:\/\/gitlab\.com\/[\w.-]+\/[\w.-]+\/?($|[?#])/i,
+  /^https?:\/\/bitbucket\.org\/[\w.-]+\/[\w.-]+\/?($|[?#])/i,
+];
+
+// Semantic markers — phrases that precede a URL/path and tag its role.
+const SEMANTIC_MARKERS = [
+  { regex: /(?:save|leave|put|store|write|drop)\s+(?:every\s+|all\s+|the\s+)?(?:outputs?|results?|files?|everything)\s+(?:on|to|in|at|here|into)\b/i, role: 'qa_repo' },
+  { regex: /(?:outputs?|results?)\s+(?:save|location|path|dir|directory|folder|here)\b/i, role: 'qa_repo' },
+  { regex: /\bqa\s+repo(?:sitory)?\b/i, role: 'qa_repo' },
+  { regex: /\b(?:test|qa)\s+(?:folder|directory|dir)\b/i, role: 'qa_repo' },
+  { regex: /\bdev(?:eloper)?\s+repo(?:sitory)?\b/i, role: 'dev_repo' },
+  { regex: /\b(?:source\s+code|source\s+repo|code\s+repo)\b/i, role: 'dev_repo' },
+  { regex: /\b(?:the\s+)?project\s+(?:is\s+)?(?:at|in|located\s+at)\b/i, role: 'dev_repo' },
+  { regex: /\b(?:live\s+(?:app|application|site)|production\s+(?:app|url|site)|running\s+(?:app|application))\b/i, role: 'app_url' },
+  { regex: /\b(?:test|run)\s+against\b/i, role: 'app_url' },
+  { regex: /\b(?:app(?:lication)?|deployed|hosted)\s+(?:url\s+)?(?:is|at)\b/i, role: 'app_url' },
+  { regex: /\b(?:has\s+a\s+)?page\s+too\b/i, role: 'app_url' },
+];
+
+const COMMON_TRAILING_WORDS = new Set([
+  'and','or','with','the','a','an','then','to','on','in','at',
+  'for','of','but','so','if','as','by','is','are','was','were',
+  'has','have','had','be','been','use','using','used',
+  'when','where','while','before','after','because','although',
+  'this','that','these','those','my','your','their','our',
+  'i','you','he','she','we','they','them','us','me',
+  'create','make','made','add','added','run','go','do','get','set',
+  'save','configure',
+  'playwright','cypress','jest','vitest','pytest','selenium',
+  'framework','robot','robotframework',
+  'project','projects','app','apps','page','pages','test','tests','act',
+]);
+
+function trimTrailingEnglishWords(path) {
+  let result = path;
+  while (true) {
+    const lastSpace = result.lastIndexOf(' ');
+    if (lastSpace === -1) break;
+    const lastWord = result.slice(lastSpace + 1).toLowerCase().replace(/[.,;:!?]+$/, '');
+    if (COMMON_TRAILING_WORDS.has(lastWord)) {
+      result = result.slice(0, lastSpace).trimEnd();
+    } else { break; }
+  }
+  return result;
+}
+
+function stripTrailingPunctuation(s) {
+  return s.replace(/[.,;:!?)\]"'`]+$/, '').trimEnd();
+}
+
+function detectUrls(text) {
+  const matches = [...text.matchAll(URL_PATTERN)];
+  return matches.map(m => stripTrailingPunctuation(m[0]));
+}
+
+function classifyUrl(url) {
+  for (const pat of TICKET_PATTERNS) { if (pat.test(url)) return 'ticket'; }
+  for (const pat of CODE_REPO_PATTERNS) { if (pat.test(url)) return 'code-repo'; }
+  return 'aut';
+}
+
+// Sentence-starting words commonly used in NL prose (preceded by a space,
+// followed by a space). When found inside a captured path, they indicate
+// the path ended and a new sentence began. Matched against the literal
+// space-preceded position to avoid false positives like \This\folder.
+const SENTENCE_START_WORDS = /\s+(?:This|That|These|Those|It|There|When|Where|While|Now|Then|After|Before|Leave|Save|Put|Store|Use|Make|Create|Run|Go|Get|Set|Add|And|But|If|Else|For|With|Once|Also|Plus|Next|Finally|Please)\s+/;
+
+function cutAtSentenceBoundary(path) {
+  if (!path) return path;
+  // Rule A: ". <space> <Capital>"  →  end of one sentence, start of another
+  const mA = path.match(/^(.*?)\.\s+[A-Z]/);
+  if (mA) return mA[1];
+  // Rule B: " <SentenceStartWord> "  →  prose sentence injected after a path
+  // (e.g. ".../foo This one is..." — no period, but clearly a new sentence)
+  const mB = path.match(SENTENCE_START_WORDS);
+  if (mB) {
+    const idx = path.indexOf(mB[0]);
+    return path.slice(0, idx);
+  }
+  return path;
+}
+
+function looksLikePath(s) {
+  if (!s) return false;
+  if (/^https?:/i.test(s)) return false;
+  if (/^[A-Z]:[\\\/]/.test(s)) return true;
+  if (/^\/[a-zA-Z0-9_]/.test(s) && s.includes('/')) return true;
+  if (/^\.\.?[\\\/]/.test(s)) return true;
+  return false;
+}
+
+function detectPaths(text) {
+  const paths = new Set();
+  const textNoUrls = text.replace(URL_PATTERN, ' ');
+
+  const quotedMatches = [...textNoUrls.matchAll(QUOTED_PATTERN)];
+  for (const m of quotedMatches) {
+    const candidate = m[1] || m[2];
+    if (looksLikePath(candidate)) paths.add(candidate);
+  }
+
+  const winMatches = [...textNoUrls.matchAll(WIN_PATH_PATTERN)];
+  for (const m of winMatches) {
+    // Split the greedy match at every "whitespace + drive-letter:" boundary
+    // so multiple Windows paths in one match get extracted independently.
+    const segments = m[0].split(/(?<=\s)(?=[A-Z]:[\\\/])/);
+    for (let p of segments) {
+      p = cutAtSentenceBoundary(p);
+      p = stripTrailingPunctuation(p);
+      p = trimTrailingEnglishWords(p);
+      p = stripTrailingPunctuation(p);
+      if (looksLikePath(p)) paths.add(p);
+    }
+  }
+
+  const unixMatches = [...textNoUrls.matchAll(UNIX_PATH_PATTERN)];
+  for (const m of unixMatches) {
+    let p = m[1];
+    p = cutAtSentenceBoundary(p);
+    p = stripTrailingPunctuation(p);
+    if (looksLikePath(p)) paths.add(p);
+  }
+
+  return [...paths];
+}
+
+function detectFramework(text) {
+  for (const [name, pat] of FRAMEWORK_PATTERNS) {
+    if (pat.test(text)) return name;
+  }
+  return null;
+}
+
+// Ticket references in FREE TEXT (not URLs): "ticket #PROJ-123", "issue 42",
+// "#v195-fixes". Keyword-anchored matches are most reliable; a standalone
+// "#id" is accepted only when it contains a digit (avoids matching plain words
+// like "#fixes"). Returns the bare id (leading "#" stripped) for branch naming.
+function detectTicketRefs(text) {
+  const refs = [];
+  const kw = text.match(/\b(?:ticket|issue|story|bug)\s+#?([A-Za-z0-9][\w.\-]*)/i);
+  if (kw) refs.push(kw[1]);
+  for (const m of text.matchAll(/(?:^|\s)#([A-Za-z0-9][\w.\-]*)/g)) {
+    if (/\d/.test(m[1]) && !refs.includes(m[1])) refs.push(m[1]);
+  }
+  return refs;
+}
+
+// Target/base branch from NL: "to the main branch", "against develop",
+// "base release/1.2", "branch staging". Anchored on the word "branch" or on
+// explicit base/target keywords so generic prose ("test against <url>") does
+// not false-trigger. Returns the branch name.
+function detectBaseBranch(text) {
+  // Strip URLs first so "test against https://..." never yields a branch like "https".
+  text = text.replace(URL_PATTERN, ' ');
+  let m = text.match(/\b(?:to|into|onto|against|targeting|target)\s+(?:the\s+)?([A-Za-z0-9][\w.\/\-]*)\s+branch\b/i);
+  if (m) return m[1];
+  m = text.match(/\b(?:base|target)\s+(?:branch\s+)?["']?([A-Za-z0-9][\w.\/\-]*)["']?/i);
+  if (m && m[1].toLowerCase() !== 'branch') return m[1];
+  m = text.match(/\bbranch\s+["']?([A-Za-z0-9][\w.\/\-]*)["']?/i);
+  if (m && m[1].toLowerCase() !== 'branch') return m[1];
+  // Bare "against/onto/into <branch>" (no "branch" keyword). Guarded against
+  // URLs/paths so "test against <url>" / "merge into /some/path" don't match.
+  m = text.match(/\b(?:against|onto|into|merge\s+(?:in)?to)\s+(?:the\s+)?["']?([A-Za-z0-9][\w.\/\-]*)["']?/i);
+  if (m && !/^https?:/i.test(m[1]) && !looksLikePath(m[1]) && m[1].toLowerCase() !== 'the') return m[1];
+  return null;
+}
+
+// Explicit PR/test title from NL — ONLY when there is clear naming intent:
+// "titled X" / "called X" / "named X", or "title: X" / "title = X" / "title is X".
+// The bare noun "title" in prose (e.g. "the path title (Foundations…") is NOT a
+// title and must not match. Free-form descriptive titles are intentionally not
+// inferred — the command agent's fallback handles those and pauses for confirmation.
+function detectTitle(text) {
+  // Capture stops at punctuation, end-of-string, or a branch preposition
+  // ("onto/into/against/base/target/branch") so "named X onto develop" → "X".
+  const END = '(?:\\s*[,.]|\\s+(?:onto|into|against|targeting|target|base|branch)\\b|$)';
+  let m = text.match(new RegExp('\\b(?:titled|called|named)\\s+["\']?([^"\'\\n,.]{2,60}?)["\']?' + END, 'i'));
+  if (m) return m[1].trim();
+  m = text.match(new RegExp('\\btitle\\s*(?::|=|\\bis\\b)\\s*["\']?([^"\'\\n,.]{2,60}?)["\']?' + END, 'i'));
+  if (m) return m[1].trim();
+  return null;
+}
+
+function detectRoleHints(text, urls, paths) {
+  const hints = { urls: {}, paths: {} };
+  const WINDOW = 80;
+
+  const findContextRole = (needle) => {
+    const idx = text.indexOf(needle);
+    if (idx === -1) return null;
+    const before = text.slice(Math.max(0, idx - WINDOW), idx);
+    let matchedRole = null;
+    let matchedDistance = Infinity;
+    for (const { regex, role } of SEMANTIC_MARKERS) {
+      const m = before.match(regex);
+      if (m) {
+        const lastIdx = before.lastIndexOf(m[0]);
+        const distance = before.length - lastIdx;
+        if (distance < matchedDistance) {
+          matchedDistance = distance;
+          matchedRole = role;
+        }
+      }
+    }
+    return matchedRole;
+  };
+
+  for (const url of urls) {
+    const r = findContextRole(url);
+    if (r) hints.urls[url] = r;
+  }
+  for (const path of paths) {
+    const r = findContextRole(path);
+    if (r) hints.paths[path] = r;
+  }
+  return hints;
+}
+
+function parseFlags(text) {
+  const flags = {};
+  const re = /--([\w-]+)(?:(?:=|\s+)(?:"([^"]+)"|'([^']+)'|(\S+)))?/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const name = m[1];
+    let value;
+    if (m[2] !== undefined) value = m[2];
+    else if (m[3] !== undefined) value = m[3];
+    else if (m[4] !== undefined && !m[4].startsWith('--')) value = m[4];
+    else value = true;
+    flags[name] = value;
+  }
+  return flags;
+}
+
+function detectIntent(args) {
+  if (typeof args !== 'string') args = String(args || '');
+
+  const flags = parseFlags(args);
+  const urls = detectUrls(args);
+  const paths = detectPaths(args);
+  const framework = detectFramework(args);
+
+  const tickets = urls.filter(u => classifyUrl(u) === 'ticket');
+  const code_repo_urls = urls.filter(u => classifyUrl(u) === 'code-repo');
+  const aut_urls = urls.filter(u => classifyUrl(u) === 'aut');
+  const role_hints = detectRoleHints(args, urls, paths);
+  const ticket_refs = detectTicketRefs(args);
+  const base_branch = detectBaseBranch(args);
+  const title = detectTitle(args);
+
+  let suggested_mode = null;
+  if (flags['ticket'] || tickets.length > 0 || ticket_refs.length > 0) suggested_mode = 'from-ticket';
+  else if (flags['app-url'] || aut_urls.length > 0) suggested_mode = 'with_app_url';
+  else if (flags['ado'] || /dev\.azure\.com|visualstudio\.com/i.test(args)) suggested_mode = 'ado';
+  else if (flags['update']) suggested_mode = 'update';
+  else if (flags['pom-only']) suggested_mode = 'pom-only';
+
+  return { urls, paths, framework, tickets, ticket_refs, base_branch, title, code_repo_urls, aut_urls, role_hints, flags, suggested_mode };
+}
+
+function resolveInputs(args, options) {
+  options = options || {};
+  const intent = detectIntent(args);
+  const aliases = options.flagAliases || {};
+  const defaults = options.defaults || {};
+
+  const pathByRole = {};
+  const unhintedPaths = [];
+  for (const p of intent.paths) {
+    const r = intent.role_hints.paths[p];
+    if (r) { (pathByRole[r] = pathByRole[r] || []).push(p); }
+    else { unhintedPaths.push(p); }
+  }
+  const urlByRole = {};
+  const unhintedAutUrls = [];
+  for (const u of intent.aut_urls) {
+    const r = intent.role_hints.urls[u];
+    if (r === 'app_url') { (urlByRole.app_url = urlByRole.app_url || []).push(u); }
+    else { unhintedAutUrls.push(u); }
+  }
+
+  const takePath = (role) => {
+    if (pathByRole[role] && pathByRole[role].length > 0) return pathByRole[role].shift();
+    if (unhintedPaths.length > 0) return unhintedPaths.shift();
+    return null;
+  };
+  const takeAutUrl = () => {
+    if (urlByRole.app_url && urlByRole.app_url.length > 0) return urlByRole.app_url.shift();
+    if (unhintedAutUrls.length > 0) return unhintedAutUrls.shift();
+    return null;
+  };
+
+  // Pre-pass: any value supplied via an EXPLICIT flag must be consumed from the
+  // NL pools, so a flag-provided path/url is never re-assigned to a DIFFERENT
+  // field. Without this, `--dev-repo <path>` resolves dev_repo from the flag but
+  // leaves <path> in the pool, and a flag-less qa_repo then grabs it — wrongly
+  // inferring qa_repo == dev_repo and flipping the pipeline into gap-fill mode.
+  for (const flagName of Object.values(aliases)) {
+    const fv = intent.flags[flagName];
+    if (typeof fv !== 'string') continue;
+    let i = unhintedPaths.indexOf(fv);
+    if (i !== -1) unhintedPaths.splice(i, 1);
+    for (const role of Object.keys(pathByRole)) {
+      const r = pathByRole[role].indexOf(fv);
+      if (r !== -1) pathByRole[role].splice(r, 1);
+    }
+    i = unhintedAutUrls.indexOf(fv);
+    if (i !== -1) unhintedAutUrls.splice(i, 1);
+    if (urlByRole.app_url) {
+      const r = urlByRole.app_url.indexOf(fv);
+      if (r !== -1) urlByRole.app_url.splice(r, 1);
+    }
+  }
+
+  const resolved = {};
+  for (const [field, flagName] of Object.entries(aliases)) {
+    if (intent.flags[flagName] !== undefined) {
+      resolved[field] = { value: intent.flags[flagName], source: 'flag' };
+      continue;
+    }
+    if (field === 'app_url') {
+      const v = takeAutUrl();
+      if (v) { resolved[field] = { value: v, source: 'NL' }; continue; }
+    } else if (field === 'dev_repo') {
+      const v = takePath('dev_repo');
+      if (v) { resolved[field] = { value: v, source: 'NL' }; continue; }
+    } else if (field === 'qa_repo') {
+      const v = takePath('qa_repo');
+      if (v) { resolved[field] = { value: v, source: 'NL' }; continue; }
+    } else if (field === 'framework' && intent.framework !== null) {
+      resolved[field] = { value: intent.framework, source: 'NL' };
+      continue;
+    } else if (field === 'ticket' && (intent.tickets.length > 0 || intent.ticket_refs.length > 0)) {
+      resolved[field] = { value: intent.tickets[0] || intent.ticket_refs[0], source: 'NL' };
+      continue;
+    } else if (field === 'base' && intent.base_branch) {
+      resolved[field] = { value: intent.base_branch, source: 'NL' };
+      continue;
+    } else if (field === 'title' && intent.title) {
+      resolved[field] = { value: intent.title, source: 'NL' };
+      continue;
+    }
+    if (defaults[field] !== undefined) {
+      resolved[field] = { value: defaults[field], source: 'default' };
+    } else {
+      resolved[field] = { value: null, source: 'default' };
+    }
+  }
+
+  for (const [flagName, flagValue] of Object.entries(intent.flags)) {
+    const isAliased = Object.values(aliases).includes(flagName);
+    if (!isAliased) {
+      const internalName = flagName.replace(/-/g, '_');
+      resolved[internalName] = { value: flagValue, source: 'flag' };
+    }
+  }
+
+  if (intent.code_repo_urls.length > 0) {
+    resolved._code_repo_urls = {
+      value: intent.code_repo_urls.join(', '),
+      source: 'NL',
+      warning: 'GitHub/GitLab/Bitbucket URL detected. --dev-repo expects a LOCAL path. Clone the repo first.',
+    };
+  }
+
+  const banner = formatInputDetection(resolved, options);
+  return { resolved, intent, banner };
+}
+
+function formatInputDetection(resolved, options) {
+  const lines = [];
+  lines.push('=== INPUT DETECTION ===');
+
+  const flagLines = [];
+  const nlLines = [];
+  const defaultLines = [];
+  const warningLines = [];
+
+  for (const [field, info] of Object.entries(resolved)) {
+    const { value, source, warning } = info;
+    if (field.startsWith('_')) {
+      if (warning) {
+        warningLines.push('  WARN: ' + warning);
+        warningLines.push('     Detected URL(s): ' + value);
+      }
+      continue;
+    }
+    const flagName = '--' + field.replace(/_/g, '-');
+    const display = formatValue(value);
+    const line = '  ' + flagName.padEnd(20) + ' ' + display + '  (source: ' + source + ')';
+    if (source === 'flag') flagLines.push(line);
+    else if (source === 'NL') nlLines.push(line);
+    else defaultLines.push(line);
+  }
+
+  if (flagLines.length > 0) { lines.push('From explicit flags:'); lines.push(...flagLines); }
+  if (nlLines.length > 0) { lines.push('Detected from natural language:'); lines.push(...nlLines); }
+  if (defaultLines.length > 0) { lines.push('Defaults applied:'); lines.push(...defaultLines); }
+  if (warningLines.length > 0) { lines.push('Warnings:'); lines.push(...warningLines); }
+
+  if (flagLines.length === 0 && nlLines.length === 0 && defaultLines.length === 0 && warningLines.length === 0) {
+    lines.push('  No inputs detected. Pipeline will use cwd / interactive prompts.');
+  }
+  lines.push('=======================');
+  return lines.join('\n');
+}
+
+function formatValue(value) {
+  if (value === null || value === undefined) return '(not set)';
+  if (value === true) return 'true';
+  if (value === false) return 'false';
+  if (typeof value === 'string') return value.includes(' ') ? '"' + value + '"' : value;
+  return String(value);
+}
+
+module.exports = {
+  detectIntent, detectUrls, detectPaths, detectFramework, detectRoleHints,
+  cutAtSentenceBoundary, parseFlags, classifyUrl, looksLikePath,
+  resolveInputs, formatInputDetection,
+};
+
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0) {
+    console.error('Usage:');
+    console.error('  node bin/lib/intent-detector.cjs "<args string>"');
+    console.error('  node bin/lib/intent-detector.cjs --resolve "<args>" [--aliases <json>]');
+    process.exit(1);
+  }
+  if (argv[0] === '--resolve') {
+    const args = argv[1] || '';
+    let aliases = {};
+    const aliasIdx = argv.indexOf('--aliases');
+    if (aliasIdx !== -1 && argv[aliasIdx + 1]) {
+      try { aliases = JSON.parse(argv[aliasIdx + 1]); }
+      catch (e) { console.error('Invalid --aliases JSON'); process.exit(1); }
+    }
+    const result = resolveInputs(args, { flagAliases: aliases });
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    const args = argv.join(' ');
+    const result = detectIntent(args);
+    console.log(JSON.stringify(result, null, 2));
+  }
+}