@capagents/forgeqe 1.1.3 → 1.1.5

package/src/code/graph/locators.ts

@@ -0,0 +1,398 @@
+/**
+ * Locators as one vocabulary, whatever wrote them: Playwright in any language (getByRole, GetByRole, get_by_role,
+ * locator), Selenium (By.id, By.Id, By.ID, find_element(By.ID, …)), Cypress (cy.get, cy.contains), WebdriverIO ($, $$,
+ * aria/ and = selectors), and Testing Library queries. Code, the handoff, and page memory all reduce to these, so the
+ * same element is recognised however each one names it.
+ */
+
+export type LocatorKind = "role" | "label" | "placeholder" | "text" | "testid" | "alt" | "title" | "id" | "name" | "css" | "xpath"
+
+/** semantic: what a user perceives (role, label, text, test id). stable: an id or attribute. brittle: XPath, positions, long CSS paths. */
+export type LocatorQuality = "semantic" | "stable" | "brittle"
+
+export type LocatorRef = {
+  kind: LocatorKind
+  /** The literal value; for role, the accessible name. "" when it comes from a parameter or variable. */
+  value: string
+  /** role: the ARIA role, lower case; "*" for a WebdriverIO aria/ selector, which matches any role. */
+  role?: string
+  /** The value is a regular expression (NameRegex, /…/, re.compile). */
+  pattern?: boolean
+  /** The value, or part of it, comes from a parameter: it finds a family of elements (one per argument). */
+  param?: boolean
+  /** testid from an attribute selector: the attribute it names (data-test), which getByTestId only finds when configured. */
+  attr?: string
+  quality: LocatorQuality
+}
+
+const SEMANTIC = new Set<LocatorKind>(["role", "label", "placeholder", "text", "testid", "alt", "title"])
+const TEST_ATTR = /^(data-(?:test|testid|test-id|qa|cy|e2e|automation-id|automationid)|data-test-[\w-]+)$/i
+
+/** A string literal's contents in any of the languages ('…', "…", `…`, @"…", $"…", r"…", f"…"); null when it is not one. */
+function literal(src: string): { value: string; param: boolean } | null {
+  const s = src.trim()
+  const m = /^(?:[@$]{1,2}|[rRfFbBuU]{1,2})?(["'`])([\s\S]*)\1$/.exec(s)
+  if (!m) return null
+  const body = m[2]
+  // Interpolations: ${x} (TS), {x} (C# $"", Python f""). Their text is a placeholder, not part of the value.
+  const interpolated = (m[1] === "`" && /\$\{[^}]+\}/.test(body)) || (/^[$fF]/.test(s) && /\{[^}]+\}/.test(body))
+  const value = interpolated ? body.replace(/\$?\{[^}]+\}/g, "\u0000") : body
+  return { value: value.replace(/\\(["'`\\])/g, "$1"), param: interpolated }
+}
+
+/** Top-level arguments of a call's argument text, split on commas outside brackets and strings. */
+export function splitArgs(args: string): string[] {
+  const out: string[] = []
+  let depth = 0
+  let quote = ""
+  let cur = ""
+  for (let i = 0; i < args.length; i++) {
+    const c = args[i]
+    if (quote) {
+      cur += c
+      if (c === "\\") cur += args[++i] ?? ""
+      else if (c === quote) quote = ""
+      continue
+    }
+    if (c === '"' || c === "'" || c === "`") quote = c
+    else if ("([{".includes(c)) depth++
+    else if (")]}".includes(c)) depth--
+    else if (c === "," && depth === 0) {
+      out.push(cur.trim())
+      cur = ""
+      continue
+    }
+    cur += c
+  }
+  if (cur.trim()) out.push(cur.trim())
+  return out
+}
+
+/** A regular expression literal or constructor: /x/i, new Regex(@"x"), re.compile(r"x"), new RegExp("x"). */
+function regexOf(src: string): string | null {
+  const s = src.trim()
+  const lit = /^\/((?:\\.|[^/])+)\/[a-z]*$/.exec(s)
+  if (lit) return lit[1]
+  const ctor = /^(?:new\s+(?:Regex|RegExp)|re\.compile|Pattern\.compile)\s*\(\s*([\s\S]+?)\s*(?:,[\s\S]*)?\)$/.exec(s)
+  if (ctor) return literal(splitArgs(ctor[1])[0] || "")?.value ?? null
+  return null
+}
+
+/** A text-like argument: a literal, a regular expression, or a parameter. */
+function textArg(src: string | undefined): { value: string; pattern?: boolean; param?: boolean } | null {
+  if (!src) return null
+  const lit = literal(src)
+  if (lit) return lit.param ? { value: lit.value, param: true } : { value: lit.value }
+  const re = regexOf(src)
+  if (re !== null) return { value: re, pattern: true }
+  // A plain identifier or member access: the value comes from a parameter or a variable.
+  if (/^[A-Za-z_][\w.]*$/.test(src.trim())) return { value: "", param: true }
+  return null
+}
+
+/** The expression that starts at `from`, up to a comma or closing bracket outside strings and brackets. */
+function expressionAt(s: string, from: number): string {
+  let depth = 0
+  let quote = ""
+  let i = from
+  for (; i < s.length; i++) {
+    const c = s[i]
+    if (quote) {
+      if (c === "\\" && quote !== "@") i++
+      else if (c === quote) quote = ""
+      continue
+    }
+    if (c === '"' || c === "'" || c === "`") quote = c
+    else if (c === "/" && i === from) {
+      // A regular expression literal: skip to its closing slash.
+      const end = /^\/(?:\\.|[^/])+\/[a-z]*/.exec(s.slice(i))
+      if (end) i += end[0].length - 1
+    } else if ("([{".includes(c)) depth++
+    else if (")]}".includes(c)) {
+      if (depth === 0) break
+      depth--
+    } else if (c === "," && depth === 0) break
+  }
+  return s.slice(from, i).trim()
+}
+
+/** The accessible name option of a role call: { name: 'x' }, new() { Name = "x" }, NameRegex = new Regex(…), name="x". */
+function nameOption(args: string[]): { value: string; pattern?: boolean; param?: boolean } | null {
+  for (const a of args.slice(1)) {
+    // { name: … }, new() { Name = … }, name=… (Python), new GetByRoleOptions().setName(…) (Java).
+    const key = /\b(name|Name|NameString|NameRegex)\s*[:=]\s*|\.(setName)\(\s*/.exec(a)
+    if (!key) continue
+    const value = expressionAt(a, (key.index ?? 0) + key[0].length)
+    const arg = textArg(value)
+    if (arg) return key[1] === "NameRegex" && !arg.pattern ? { value: "", param: true } : arg
+    return { value: "", param: true }
+  }
+  return null
+}
+
+/** AriaRole.Button, 'button', "BUTTON", AriaRole.BUTTON → button. */
+function roleOf(src: string | undefined): string {
+  if (!src) return ""
+  const lit = literal(src)
+  if (lit) return lit.param ? "" : lit.value.toLowerCase()
+  const m = /(?:AriaRole|Role)\.(\w+)$/.exec(src.trim())
+  return m ? m[1].toLowerCase() : ""
+}
+
+function cssQuality(css: string): LocatorQuality {
+  if (/:nth-(?:child|of-type)|:eq\(|:first-child|:last-child/.test(css)) return "brittle"
+  const parts = css.trim().split(/\s*[\s>+~]\s*/).filter(Boolean)
+  return parts.length >= 3 ? "brittle" : "stable"
+}
+
+/** A CSS selector reduced to what it says: an id, a test id, a name, a label, or plain CSS. */
+export function fromCss(raw: string): LocatorRef {
+  const css = raw.trim()
+  const id = /^#([\w-]+)$/.exec(css) || /^\[id\s*=\s*['"]?([^'"\]]+)['"]?\]$/.exec(css)
+  if (id) return { kind: "id", value: id[1], quality: "stable" }
+  const attr = /^(\w+)?\[([\w-]+)\s*=\s*['"]?([^'"\]]+)['"]?\]$/.exec(css)
+  if (attr && TEST_ATTR.test(attr[2])) return { kind: "testid", value: attr[3], attr: attr[2], quality: "semantic" }
+  if (attr && attr[2] === "name") return { kind: "name", value: attr[3], quality: "stable" }
+  if (attr && attr[2] === "aria-label") return { kind: "label", value: attr[3], quality: "semantic" }
+  if (attr && attr[2] === "placeholder") return { kind: "placeholder", value: attr[3], quality: "semantic" }
+  return { kind: "css", value: css, quality: cssQuality(css) }
+}
+
+/** A Playwright selector string: css, xpath=, //…, text=, id=, data-testid=, role=…[name=…]. */
+function fromSelector(raw: string, param: boolean): LocatorRef {
+  const s = raw.trim()
+  const ref = ((): LocatorRef => {
+    if (/^xpath=/.test(s)) return { kind: "xpath", value: s.slice(6), quality: "brittle" }
+    if (/^\.?\/\/|^\(\/\//.test(s)) return { kind: "xpath", value: s, quality: "brittle" }
+    if (/^text=/.test(s)) return { kind: "text", value: s.slice(5).replace(/^["']|["']$/g, ""), quality: "semantic" }
+    if (/^id=/.test(s)) return { kind: "id", value: s.slice(3), quality: "stable" }
+    const tid = /^(data-[\w-]+)=(.+)$/.exec(s)
+    if (tid && TEST_ATTR.test(tid[1])) return { kind: "testid", value: tid[2].replace(/^["']|["']$/g, ""), quality: "semantic" }
+    const role = /^role=(\w+)(?:\[name=["']?([^"'\]]+)["']?\])?$/.exec(s)
+    if (role) return { kind: "role", role: role[1].toLowerCase(), value: role[2] || "", quality: "semantic" }
+    return fromCss(s.replace(/^css=/, ""))
+  })()
+  return param ? { ...ref, param: true } : ref
+}
+
+/** A WebdriverIO selector: aria/Name, =Link text, *=partial, #id, CSS, XPath. */
+function fromWdio(raw: string, param: boolean): LocatorRef {
+  const s = raw.trim()
+  const ref = ((): LocatorRef => {
+    if (s.startsWith("aria/")) return { kind: "role", role: "*", value: s.slice(5), quality: "semantic" }
+    if (/^\*?=/.test(s)) return { kind: "text", value: s.replace(/^\*?=/, ""), quality: "semantic" }
+    if (/^<\w+\s*\/>$/.test(s)) return { kind: "css", value: s, quality: "stable" }
+    return fromSelector(s, false)
+  })()
+  return param ? { ...ref, param: true } : ref
+}
+
+/** Selenium's By kinds, in any language's spelling: id, Id, ID, cssSelector, CssSelector, CSS_SELECTOR, … */
+function fromBy(kind: string, raw: string, param: boolean): LocatorRef | null {
+  const k = kind.toLowerCase().replace(/_/g, "")
+  const ref = ((): LocatorRef | null => {
+    if (k === "id") return { kind: "id", value: raw, quality: "stable" }
+    if (k === "name") return { kind: "name", value: raw, quality: "stable" }
+    if (k === "cssselector" || k === "css") return fromCss(raw)
+    if (k === "xpath") return { kind: "xpath", value: raw, quality: "brittle" }
+    if (k === "linktext" || k === "partiallinktext") return { kind: "text", value: raw, quality: "semantic" }
+    if (k === "classname") return { kind: "css", value: `.${raw}`, quality: "stable" }
+    if (k === "tagname") return { kind: "css", value: raw, quality: "stable" }
+    return null
+  })()
+  return ref && param ? { ...ref, param: true } : ref
+}
+
+/** Selenium's By kinds as a ref: locatorFromBy("cssSelector", "#a"), locatorFromBy("ID", "user-name"). */
+export function locatorFromBy(kind: string, value: string): LocatorRef | null {
+  return fromBy(kind, value, false)
+}
+
+/**
+ * A string that reads as a selector, kept in a constant or field to pass to locator() later: "#login",
+ * "[data-test='username']", ".cart_item", "input[name=q]", "//div[2]", "xpath=…", "text=…". Not URLs or prose.
+ */
+export function selectorLike(s: string): boolean {
+  const t = s.trim()
+  if (!t || t.length > 200 || /:\/\//.test(t) || /\s{2,}/.test(t)) return false
+  if (/^(xpath=|css=|text=|id=|data-[\w-]+=|\/\/|\(\/\/|\.\/\/)/.test(t)) return true
+  if (/\.(json|js|ts|html?|png|jpe?g|csv|xml|ya?ml|txt|md|cs|java|py)$/i.test(t)) return false
+  // CSS: every part between combinators is a simple selector, and at least one has an id, class, attribute, or pseudo.
+  const parts = t.split(/\s*[>+~]\s*|\s+/).filter(Boolean)
+  const simple = /^([a-z][\w-]*|\*)?((#|\.)[\w-]+|\[[^\]]+\]|:{1,2}[\w-]+(\([^)]*\))?)*$/
+  return parts.every((p) => simple.test(p)) && parts.some((p) => /[#.[:]/.test(p))
+}
+
+/** A selector string's locator (Playwright selector syntax, which includes CSS and XPath). */
+export function fromSelectorString(raw: string): LocatorRef {
+  return fromSelector(raw, false)
+}
+
+const BY_QUERY = /^(?:get|find|query)(?:all)?by(role|text|labeltext|label|placeholdertext|placeholder|testid|alttext|title|displayvalue)$/
+
+/** Callee names that can build a locator, lower case without underscores. */
+export const LOCATOR_CALLEES = new Set([
+  "locator",
+  "$",
+  "$$",
+  "get",
+  "contains",
+  "findelement",
+  "findelements",
+  "queryselector",
+  "queryselectorall",
+  "waitforselector",
+])
+
+/**
+ * The locator a call builds, from its callee, the receiver it is called on, and its argument text (without the
+ * parentheses); null when the call builds none.
+ */
+export function locatorFromCall(callee: string, receiver: string, argText: string): LocatorRef | null {
+  const name = callee.replace(/_/g, "").toLowerCase()
+  const args = splitArgs(argText)
+  // Selenium By.id("x"), By.Id("x"), By.cssSelector("x").
+  if (/^By$/i.test(receiver.split(".").pop() || "")) {
+    const arg = textArg(args[0])
+    return arg && !arg.pattern ? fromBy(name, arg.value, Boolean(arg.param)) : null
+  }
+  // Python Selenium: find_element(By.ID, "x").
+  if ((name === "findelement" || name === "findelements") && /^By\.\w+$/.test(args[0] || "")) {
+    const arg = textArg(args[1])
+    return arg && !arg.pattern ? fromBy(args[0].slice(3), arg.value, Boolean(arg.param)) : null
+  }
+  const q = BY_QUERY.exec(name)
+  if (q) {
+    const kind = q[1]
+    if (kind === "role") {
+      const role = roleOf(args[0])
+      if (!role && !/^[A-Za-z_][\w.]*$/.test((args[0] || "").trim())) return null
+      const opt = nameOption(args)
+      return { kind: "role", role: role || "*", value: opt?.value || "", ...(opt?.pattern ? { pattern: true } : {}), ...(opt?.param || !role ? { param: true } : {}), quality: "semantic" }
+    }
+    const arg = textArg(args[0])
+    if (!arg) return null
+    const map: Record<string, LocatorKind> = { text: "text", labeltext: "label", label: "label", placeholdertext: "placeholder", placeholder: "placeholder", testid: "testid", alttext: "alt", title: "title", displayvalue: "text" }
+    return { kind: map[kind], value: arg.value, ...(arg.pattern ? { pattern: true } : {}), ...(arg.param ? { param: true } : {}), quality: "semantic" }
+  }
+  if (!LOCATOR_CALLEES.has(name)) return null
+  const arg = textArg(args[0])
+  if (!arg || arg.pattern) return null
+  if (name === "contains") return receiver === "cy" || receiver.endsWith(".cy") ? { kind: "text", value: arg.value, ...(arg.param ? { param: true } : {}), quality: "semantic" } : null
+  if (name === "get" && receiver !== "cy") return null
+  if (arg.param && !arg.value.replace(/\u0000/g, "")) return null
+  if (name === "$" || name === "$$") return fromWdio(arg.value, Boolean(arg.param))
+  return fromSelector(arg.value, Boolean(arg.param))
+}
+
+/** The locator a Playwright expression like the handoff's builds: page.getByRole("button", { name: "Go" }), page.locator("#q"). */
+export function locatorFromExpression(expr: string): LocatorRef | null {
+  // The last locator-building call in a chain wins: page.locator("#a").getByRole(…) is the role inside #a.
+  const calls = [...expr.matchAll(/(?:([\w$.]+)\.)?([\w$]+)\s*\(/g)]
+  for (let i = calls.length - 1; i >= 0; i--) {
+    const c = calls[i]
+    const open = (c.index ?? 0) + c[0].length
+    let depth = 1
+    let j = open
+    let quote = ""
+    for (; j < expr.length && depth; j++) {
+      const ch = expr[j]
+      if (quote) {
+        if (ch === "\\") j++
+        else if (ch === quote) quote = ""
+      } else if (ch === '"' || ch === "'" || ch === "`") quote = ch
+      else if (ch === "(") depth++
+      else if (ch === ")") depth--
+    }
+    const ref = locatorFromCall(c[2], c[1] || "", expr.slice(open, j - 1))
+    if (ref) return ref
+  }
+  return null
+}
+
+/** Page memory's locator types (test_id, id, role "button|Name", label, …) as LocatorRefs. */
+export function fromMemory(type: string | undefined, value: string | undefined): LocatorRef | null {
+  if (!type || !value) return null
+  switch (type) {
+    case "role": {
+      const [role, ...name] = value.split("|")
+      return { kind: "role", role: role.toLowerCase(), value: name.join("|"), quality: "semantic" }
+    }
+    case "test_id":
+      return { kind: "testid", value, quality: "semantic" }
+    case "id":
+    case "name":
+    case "label":
+    case "placeholder":
+    case "text":
+    case "alt":
+    case "title":
+      return { kind: type, value, quality: SEMANTIC.has(type) ? "semantic" : "stable" }
+    case "css":
+      return fromCss(value)
+    case "xpath":
+      return { kind: "xpath", value, quality: "brittle" }
+    default:
+      return null
+  }
+}
+
+const norm = (s: string) => s.replace(/[\s ]+/g, " ").trim().toLowerCase()
+
+function patternMatches(pattern: string, value: string): boolean {
+  try {
+    return new RegExp(pattern.replace(/^\(\?i\)/, ""), "i").test(value)
+  } catch {
+    return false
+  }
+}
+
+/** A template value with a parameter hole (\u0000) against a concrete value. */
+function templateMatches(template: string, value: string): boolean {
+  const parts = template.split("\u0000").map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+  return new RegExp(`^${parts.join(".+")}$`, "i").test(value.trim())
+}
+
+/**
+ * How a locator in code finds a concrete locator of an element: "exact" (the same value), "pattern" (its regular
+ * expression or template matches), "param" (the same role or kind, with the value left to an argument), or null.
+ */
+export function matchLocator(code: LocatorRef, element: LocatorRef): "exact" | "pattern" | "param" | null {
+  if (code.kind !== element.kind) {
+    // text= and getByText also find a role's accessible name when it is the element's text.
+    if (!(code.kind === "text" && element.kind === "role")) return null
+  }
+  if (code.kind === "role" && element.kind === "role" && code.role !== "*" && element.role !== "*" && code.role !== element.role) return null
+  const value = element.value
+  if (code.pattern) return value && patternMatches(code.value, value) ? "pattern" : null
+  if (code.param) {
+    if (code.value.includes("\u0000")) return value && templateMatches(code.value, value) ? "pattern" : null
+    // A role with its name from an argument still names a role; any other kind with no literal says too little.
+    return code.kind === "role" && code.role !== "*" ? "param" : null
+  }
+  if (code.kind === "css" && code.value !== value) return compoundWithin(code.value, value) ? "exact" : null
+  if (code.kind === "css" || code.kind === "xpath" || code.kind === "id" || code.kind === "testid" || code.kind === "name") return code.value === value ? "exact" : null
+  return norm(code.value) === norm(value) ? "exact" : null
+}
+
+/** tag.class selectors: ".cart_link" is within "a.cart_link.big" (its tag agrees and its classes are among the other's). */
+function compoundWithin(code: string, element: string): boolean {
+  const parse = (css: string) => {
+    const m = /^([a-z][\w-]*)?((?:\.[\w-]+)+)$/i.exec(css.trim())
+    return m ? { tag: (m[1] || "").toLowerCase(), classes: m[2].slice(1).split(".") } : null
+  }
+  const c = parse(code)
+  const e = parse(element)
+  if (!c || !e) return false
+  return (!c.tag || c.tag === e.tag) && c.classes.every((x) => e.classes.includes(x))
+}
+
+/** One line for a locator: role button "Sign in", id #login-button, xpath //tr[…]. */
+export function describeLocator(l: LocatorRef): string {
+  const v = l.pattern ? `/${l.value}/` : l.param && !l.value ? "(from a parameter)" : JSON.stringify(l.value.replace(/\u0000/g, "{…}"))
+  if (l.kind === "role") return `role ${l.role === "*" ? "any" : l.role}${l.value || l.param || l.pattern ? ` ${v}` : ""}`
+  if (l.kind === "id") return `id #${l.value}`
+  // An attribute selector stays one: getByTestId finds it only when the repository sets that attribute as its test id.
+  if (l.kind === "testid" && l.attr) return `testid [${l.attr}=${v}]`
+  return `${l.kind} ${v}`
+}