@qa-gentic/stlc-agents 1.0.27 → 1.0.28

package/src/stlc_agents/agent_migration/transformer/local_var_hoister.py

@@ -0,0 +1,378 @@
+"""
+Hoist inline-string locators from local variables into the centralised
+xxxLocators objects, then rewrite the variable RHS to reference the new entry.
+
+Input (page object):
+    const banner = this.page.getByTestId("nova_impersonate-banner");
+    const saveBtn = this.page.getByRole("button", { name: "Save" });
+
+Output (page object):
+    const banner = this.page.getByTestId(novaImpersonateLocators.banner.selector);
+    const saveBtn = this.page.locator(novaImpersonateLocators.saveBtn.selector);
+
+Side effect: emits hoist actions describing entries to be appended to the
+target locator file's xxxLocators object literal during a post-pass.
+
+Hoist matrix:
+    .locator("CSS")                       → selector "CSS"
+    .getByTestId("X")                     → selector "[data-testid=\"X\"]"
+    .getByRole("R")                       → selector "role=R"
+    .getByRole("R", { name: "N" })        → selector "role=R[name=\"N\"]"
+    .getByText("T")                       → selector "text=\"T\""
+    .getByLabel(...)                      → skipped (no clean string form)
+    template strings with ${}             → skipped
+    already-centralised xxxLocators refs  → skipped
+"""
+from __future__ import annotations
+import re
+from dataclasses import dataclass
+
+
+# ---------------------------------------------------------------------------
+# Hoist action — emitted during per-file scan, applied in the post-pass.
+# ---------------------------------------------------------------------------
+
+@dataclass
+class HoistAction:
+    locator_object: str   # e.g. "invoiceManagementLocators"
+    entry_name:     str   # e.g. "chargebeeContent"
+    selector:       str   # the static-string selector value
+    intent:         str   # human-readable
+    stability:      int   # 0-100
+
+
+# ---------------------------------------------------------------------------
+# Heuristics — mirrored from locator_registrar.py so hoisted entries have the
+# same shape and stability scoring as the original locator-file entries.
+# ---------------------------------------------------------------------------
+
+def _camel_to_words(name: str) -> str:
+    s = re.sub(r"([A-Z])", r" \1", name)
+    return s.strip().lower()
+
+
+def _infer_stability(selector: str) -> int:
+    """0-100 confidence. Mirrors locator_registrar._infer_stability."""
+    if "[data-testid" in selector or "data-testid=" in selector:
+        return 100
+    if selector.startswith("role="):
+        return 80
+    if selector.startswith("text="):
+        return 50
+    if selector.startswith("#"):
+        return 80
+    if re.match(r"^[a-z_][\w-]*$", selector):
+        return 80
+    if "[aria-label=" in selector or "[placeholder=" in selector:
+        return 70
+    if "[dusk=" in selector or "[data-" in selector:
+        return 70
+    if selector.startswith(".") or any(c in selector for c in ">+~"):
+        return 30
+    return 50
+
+
+# ---------------------------------------------------------------------------
+# Regexes for the various RHS shapes we know how to hoist.
+# ---------------------------------------------------------------------------
+
+# `const|let|var|private|public|protected|readonly [readonly] <name> [: T] = <rhs>;`
+# DOTALL so multi-line RHS is captured.
+_VAR_ASSIGN_RE = re.compile(
+    r"\b((?:const|let|var|private|public|protected|readonly)"
+    r"(?:\s+(?:private|public|protected|readonly))*"
+    r"\s+(\w+)(?:\s*:\s*[^=;]+)?\s*=\s*)"
+    r"(.+?);",
+    re.DOTALL,
+)
+
+# Inside an RHS, match the LAST `.locator("...")` / `.getByXxx(...)` call.
+# Quoted strings: prefer double-quoted, fall back to single-quoted. We avoid
+# backreferences because backreference numbers shift when patterns are composed.
+_DQ   = r'"([^"]*)"'           # 1 capture: content
+_SQ   = r"'([^']*)'"            # 1 capture: content
+_QSTR = rf"(?:{_DQ}|{_SQ})"    # 2 captures: (dq, sq) — one will be non-None
+
+_LOCATOR_CALL_RE  = re.compile(rf"\.locator\(\s*{_QSTR}\s*,?\s*\)", re.DOTALL)
+_TESTID_CALL_RE   = re.compile(rf"\.getByTestId\(\s*{_QSTR}\s*,?\s*\)", re.DOTALL)
+_TEXT_CALL_RE     = re.compile(rf"\.getByText\(\s*{_QSTR}\s*,?\s*\)", re.DOTALL)
+# getByRole supports an optional second arg `{ name: "..." }` (strings only — we skip regex).
+_ROLE_CALL_RE = re.compile(
+    rf"\.getByRole\(\s*{_QSTR}"
+    rf"(?:\s*,\s*\{{\s*name\s*:\s*{_QSTR}\s*\}})?"
+    rf"\s*,?\s*\)",
+    re.DOTALL,
+)
+
+
+def _qstr_pick(m: re.Match, base: int) -> str:
+    """Given a 2-capture _QSTR pair starting at group `base`, return the matched string."""
+    return m.group(base) if m.group(base) is not None else (m.group(base + 1) or "")
+
+# Detect already-centralised access — skip hoisting if RHS already references it.
+_LOCATOR_ACCESS_RE = re.compile(r"\b\w+Locators\.\w+\b")
+
+# Detect template-string interpolation — skip if present anywhere in RHS.
+_INTERP_RE = re.compile(r"`[^`]*\$\{[^}]*\}[^`]*`")
+
+# Identify the page object's primary xxxLocators import.
+# `import { fooLocators[, barLocators...] } from "<path>";`
+_LOCATOR_IMPORT_RE = re.compile(
+    r"""import\s+\{([^}]+)\}\s+from\s+['"]([^'"]+)['"]\s*;?"""
+)
+
+
+# ---------------------------------------------------------------------------
+# Per-RHS hoist detection — returns (new_rhs, selector_value, stability) or None.
+# ---------------------------------------------------------------------------
+
+def _try_hoist_rhs(rhs: str, var_name: str) -> tuple[str, str, str, int] | None:
+    """
+    If `rhs` contains a hoistable static-string locator call, return:
+        (receiver_prefix, trailing_suffix, selector_value, stability)
+
+    `receiver_prefix` is everything in `rhs` BEFORE the matched call
+    (e.g. `this.page` or `await this.page.frameLocator(x)`).
+    `trailing_suffix` is everything AFTER the call (e.g. `.textContent()` or
+    a closing `)` from an outer wrapper like `.or(...)`).
+
+    Callers reassemble as: <prefix>.locator(<repo_ref>)<suffix>.
+    """
+    # Skip if anything in the RHS is already centralised — no point hoisting.
+    if _LOCATOR_ACCESS_RE.search(rhs):
+        return None
+    # Skip template-string interpolation — selector is dynamic.
+    if _INTERP_RE.search(rhs):
+        return None
+
+    # Find ALL call-site matches and pick the LAST one so we hoist the
+    # innermost-applied selector (the rightmost in the chain). The receiver
+    # (everything to its left) is kept verbatim.
+    candidates: list[tuple[int, int, str]] = []   # (start, end, selector_value)
+    for m in _LOCATOR_CALL_RE.finditer(rhs):
+        sel = _qstr_pick(m, 1)
+        candidates.append((m.start(), m.end(), sel))
+    for m in _TESTID_CALL_RE.finditer(rhs):
+        v = _qstr_pick(m, 1)
+        candidates.append((m.start(), m.end(), f"[data-testid=\"{v}\"]"))
+    for m in _TEXT_CALL_RE.finditer(rhs):
+        v = _qstr_pick(m, 1)
+        candidates.append((m.start(), m.end(), f"text=\"{v}\""))
+    for m in _ROLE_CALL_RE.finditer(rhs):
+        role = _qstr_pick(m, 1)
+        # Groups 3+4 are the optional `name:` value (one of dq/sq); may both be None.
+        name = m.group(3) if m.group(3) is not None else m.group(4)
+        sel = f"role={role}[name=\"{name}\"]" if name else f"role={role}"
+        candidates.append((m.start(), m.end(), sel))
+
+    if not candidates:
+        return None
+
+    candidates.sort(key=lambda t: t[0])
+    last_start, last_end, selector_value = candidates[-1]
+
+    return (
+        rhs[:last_start],
+        rhs[last_end:],
+        selector_value,
+        _infer_stability(selector_value),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Public entry — invoked from the per-file pipeline for page_object/step_def.
+# ---------------------------------------------------------------------------
+
+def hoist_inline_locators(content: str) -> tuple[str, list[HoistAction], list[str]]:
+    """
+    Scan `content` for hoistable local variable assignments and rewrite them
+    in place.
+
+    Returns:
+      (new_content, hoist_actions, changes)
+
+    hoist_actions: HoistAction list to be merged into the target locator file
+    during a post-pass. The post-pass groups by `locator_object` and appends
+    entries to the matching xxxLocators object literal.
+
+    changes: human-readable change descriptions for the migration report.
+    """
+    # Find the primary xxxLocators import. If none, nothing to hoist into.
+    primary_locator_obj = _primary_locator_object(content)
+    if not primary_locator_obj:
+        return content, [], []
+
+    actions: list[HoistAction] = []
+    changes: list[str] = []
+    used_entry_names: set[str] = set()
+
+    def _replace(m: re.Match) -> str:
+        prefix   = m.group(1)
+        var_name = m.group(2)
+        rhs      = m.group(3)
+        hoist = _try_hoist_rhs(rhs, var_name)
+        if not hoist:
+            return m.group(0)
+        receiver_prefix, trailing_suffix, selector_value, stability = hoist
+
+        # Pick an entry name. Default to the var name; suffix on collision.
+        entry_name = var_name
+        n = 2
+        while entry_name in used_entry_names:
+            entry_name = f"{var_name}{n}"
+            n += 1
+        used_entry_names.add(entry_name)
+
+        intent = _camel_to_words(entry_name) or entry_name
+        actions.append(HoistAction(
+            locator_object=primary_locator_obj,
+            entry_name=entry_name,
+            selector=selector_value,
+            intent=intent,
+            stability=stability,
+        ))
+        changes.append(
+            f"hoist {var_name} → {primary_locator_obj}.{entry_name} "
+            f"(selector={selector_value!r}, stability={stability})"
+        )
+
+        # Reconstruct the RHS: receiver + `.locator(<repo-ref>)` + whatever came
+        # after the matched call (`.textContent()`, `.first()`, outer `.or(...)`'s
+        # closing `)`, etc.). Even if the original was getByRole/getByText/
+        # getByTestId, we collapse to `.locator(...)` because the hoisted selector
+        # string is in Playwright's universal selector syntax.
+        repo_ref = f"{primary_locator_obj}.{entry_name}.selector"
+        new_rhs  = f"{receiver_prefix}.locator({repo_ref}){trailing_suffix}"
+        return f"{prefix}{new_rhs};"
+
+    new_content = _VAR_ASSIGN_RE.sub(_replace, content)
+    return new_content, actions, changes
+
+
+def _primary_locator_object(content: str) -> str | None:
+    """
+    Return the name of the xxxLocators object imported by this file. If the
+    file imports multiple xxxLocators in the same statement, prefer the first
+    one that ISN'T `sharedLocators` — page-specific entries should land in
+    the page-specific object, not the shared bucket.
+    """
+    fallback = None
+    for m in _LOCATOR_IMPORT_RE.finditer(content):
+        names_raw = m.group(1)
+        names = [n.strip() for n in names_raw.split(",") if n.strip().endswith("Locators")]
+        if not names:
+            continue
+        # Prefer a non-shared object.
+        for n in names:
+            if n != "sharedLocators":
+                return n
+        fallback = fallback or names[0]
+    return fallback
+
+
+# ---------------------------------------------------------------------------
+# Post-pass — apply buffered HoistActions to an already-modernised locator file.
+# ---------------------------------------------------------------------------
+
+# Match `export const xxxLocators = {` and locate its closing `} as const;` /
+# `};` so we can splice new entries in just before it.
+_BLOCK_OPEN_RE = re.compile(
+    r"(export\s+const\s+(\w+Locators)\s*=\s*)\{",
+)
+
+
+def append_entries_to_locator_file(
+    content: str,
+    entries_by_object: dict[str, list[HoistAction]],
+) -> tuple[str, list[str]]:
+    """
+    For each xxxLocators block in the file, append any HoistActions targeted
+    at it just before the closing brace.
+
+    Idempotent: skips entries whose `entry_name` is already a key in the block.
+    """
+    changes: list[str] = []
+    output: list[str] = []
+    cursor = 0
+
+    for m in _BLOCK_OPEN_RE.finditer(content):
+        block_name  = m.group(2)
+        body_start  = m.end()   # one past the `{`
+
+        depth = 1
+        j = body_start
+        while j < len(content) and depth > 0:
+            c = content[j]
+            if c == "{":
+                depth += 1
+            elif c == "}":
+                depth -= 1
+            j += 1
+        # j now points to one past the closing `}`.
+        body         = content[body_start : j - 1]
+        close_brace  = content[j - 1 : j]
+
+        entries = entries_by_object.get(block_name, [])
+        if not entries:
+            output.append(content[cursor:j])
+            cursor = j
+            continue
+
+        # Dedupe — skip entries already present as keys in the block body.
+        existing_keys = set(re.findall(r"^\s*(\w+)\s*:", body, re.MULTILINE))
+        to_add = [e for e in entries if e.entry_name not in existing_keys]
+        if not to_add:
+            output.append(content[cursor:j])
+            cursor = j
+            continue
+
+        # Find the last non-empty line of the body to figure out the indent.
+        body_lines = body.rstrip("\n").splitlines()
+        indent = "  "
+        for line in reversed(body_lines):
+            stripped = line.lstrip()
+            if stripped:
+                indent = line[: len(line) - len(stripped)]
+                break
+
+        # Ensure the body's last entry ends with a comma so our appends are valid.
+        body_rstripped = body.rstrip()
+        needs_comma = bool(body_rstripped) and not body_rstripped.endswith((",", "{"))
+        appended_lines = []
+        if needs_comma:
+            appended_lines.append(",")
+        for e in to_add:
+            sel_lit = _ts_string_literal(e.selector)
+            intent_lit = _ts_string_literal(e.intent)
+            appended_lines.append(
+                f"\n{indent}{e.entry_name}: {{ selector: {sel_lit}, "
+                f"intent: {intent_lit}, stability: {e.stability} }},"
+            )
+            changes.append(f"hoisted {block_name}.{e.entry_name} ({e.selector!r})")
+
+        # Splice: everything up to the last newline before `}`, then our appends,
+        # then the original trailing whitespace + `}`.
+        # Find where the closing brace's leading whitespace starts (so the `}`
+        # stays correctly indented).
+        close_lead_start = j - 1
+        while close_lead_start > body_start and content[close_lead_start - 1] in " \t":
+            close_lead_start -= 1
+        if close_lead_start > body_start and content[close_lead_start - 1] == "\n":
+            close_lead_start -= 1
+
+        output.append(content[cursor:close_lead_start])
+        output.append("".join(appended_lines))
+        output.append(content[close_lead_start:j])
+        cursor = j
+
+    output.append(content[cursor:])
+    return "".join(output), changes
+
+
+def _ts_string_literal(s: str) -> str:
+    """Render a Python string as a TypeScript double-quoted literal, escaping as needed."""
+    if "\"" in s and "'" not in s:
+        # Use single quotes so we don't need to escape the double quotes.
+        return "'" + s.replace("\\", "\\\\") + "'"
+    escaped = s.replace("\\", "\\\\").replace("\"", "\\\"")
+    return f"\"{escaped}\""

package/src/stlc_agents/agent_migration/transformer/locator_moderniser.py

@@ -0,0 +1,132 @@
+"""Modernise Playwright locator patterns to the recommended accessible-name API."""
+from __future__ import annotations
+import re
+
+# ---------------------------------------------------------------------------
+# Patterns that map cleanly to a modern Playwright locator method
+# ---------------------------------------------------------------------------
+
+# page.locator('[data-testid="x"]')  →  page.getByTestId('x')
+_TESTID_RE = re.compile(
+    r"""(?:page|this\.page)\s*\.\s*locator\(\s*['\"]\[data-testid=['\"]([^'\"]+)['\"]\]['\"]"""
+    r"""\s*\)""",
+    re.DOTALL,
+)
+
+# page.locator('text=Foo')  →  page.getByText('Foo')
+_TEXT_EQ_RE = re.compile(
+    r"""(?:page|this\.page)\s*\.\s*locator\(\s*['\"]\s*text\s*=\s*([^'\"]+?)\s*['\"]"""
+    r"""\s*\)"""
+)
+
+# page.locator(':text("Foo")') / page.locator(':text-is("Foo")')
+_TEXT_PSEUDO_RE = re.compile(
+    r"""(?:page|this\.page)\s*\.\s*locator\(\s*['\"]\s*:text(?:-is)?\(['\"](.*?)['\"]\)"""
+    r"""['\"]"""
+    r"""\s*\)"""
+)
+
+# page.locator('[placeholder="Foo"]')
+_PLACEHOLDER_RE = re.compile(
+    r"""(?:page|this\.page)\s*\.\s*locator\(\s*['\"]\[placeholder=['\"]([^'\"]+)['\"]\]['\"]"""
+    r"""\s*\)"""
+)
+
+# page.locator('[aria-label="Foo"]')
+_ARIA_LABEL_RE = re.compile(
+    r"""(?:page|this\.page)\s*\.\s*locator\(\s*['\"]\[aria-label=['\"]([^'\"]+)['\"]\]['\"]"""
+    r"""\s*\)"""
+)
+
+# page.locator('role=button[name="Submit"]')
+_ROLE_RE = re.compile(
+    r"""(?:page|this\.page)\s*\.\s*locator\(\s*['\"]\s*role\s*=\s*(\w+)\[name=['\"]([^'\"]+)['\"]\]['\"]"""
+    r"""\s*\)"""
+)
+
+# ---------------------------------------------------------------------------
+# Patterns that are too complex for auto-conversion — flag with TODO
+# ---------------------------------------------------------------------------
+
+_XPATH_RE = re.compile(
+    r"""(?:page|this\.page)\s*\.\s*locator\(\s*"""
+    r"""(?:'[^']*(?:xpath=)?//[^']*'|"[^"]*(?:xpath=)?//[^"]*")"""
+    r"""\s*\)"""
+)
+
+_COMPLEX_CSS_RE = re.compile(
+    r"""(?:page|this\.page)\s*\.\s*locator\(\s*['\"]\s*[^'\"]*"""
+    r"""(?:\s+>\s+|\s+\+\s+|\s+~\s+|:{1,2}[\w-]+\(|nth-child|nth-of-type)[^'\"]*['\"]"""
+    r"""\s*\)"""
+)
+
+_TODO_COMMENT = "/* TODO: convert to getByRole when accessible name is known */"
+
+
+def modernise_locators(content: str) -> tuple[str, list[str], int]:
+    """
+    Modernise Playwright locator patterns.
+    Returns (transformed_content, changes, todo_count).
+    """
+    changes: list[str] = []
+    todo_count = 0
+
+    def _sub_testid(m: re.Match) -> str:
+        tid = m.group(1)
+        prefix = "this.page" if "this.page" in m.group(0) else "page"
+        changes.append(f"[data-testid='{tid}'] → getByTestId('{tid}')")
+        return f"{prefix}.getByTestId('{tid}')"
+
+    def _sub_text_eq(m: re.Match) -> str:
+        text = m.group(1).strip()
+        prefix = "this.page" if "this.page" in m.group(0) else "page"
+        changes.append(f"text={text!r} → getByText('{text}')")
+        return f"{prefix}.getByText('{text}')"
+
+    def _sub_text_pseudo(m: re.Match) -> str:
+        text = m.group(1)
+        prefix = "this.page" if "this.page" in m.group(0) else "page"
+        changes.append(f":text('{text}') → getByText('{text}')")
+        return f"{prefix}.getByText('{text}')"
+
+    def _sub_placeholder(m: re.Match) -> str:
+        ph = m.group(1)
+        prefix = "this.page" if "this.page" in m.group(0) else "page"
+        changes.append(f"[placeholder='{ph}'] → getByPlaceholder('{ph}')")
+        return f"{prefix}.getByPlaceholder('{ph}')"
+
+    def _sub_aria_label(m: re.Match) -> str:
+        lbl = m.group(1)
+        prefix = "this.page" if "this.page" in m.group(0) else "page"
+        changes.append(f"[aria-label='{lbl}'] → getByLabel('{lbl}')")
+        return f"{prefix}.getByLabel('{lbl}')"
+
+    def _sub_role(m: re.Match) -> str:
+        role, name = m.group(1), m.group(2)
+        prefix = "this.page" if "this.page" in m.group(0) else "page"
+        changes.append(f"role={role}[name='{name}'] → getByRole('{role}', {{ name: '{name}' }})")
+        return f"{prefix}.getByRole('{role}', {{ name: '{name}' }})"
+
+    def _flag_xpath(m: re.Match) -> str:
+        nonlocal todo_count
+        todo_count += 1
+        return f"{_TODO_COMMENT} {m.group(0)}"
+
+    def _flag_complex(m: re.Match) -> str:
+        nonlocal todo_count
+        original = m.group(0)
+        if _TODO_COMMENT in original:
+            return original
+        todo_count += 1
+        return f"{_TODO_COMMENT} {original}"
+
+    content = _TESTID_RE.sub(_sub_testid, content)
+    content = _TEXT_EQ_RE.sub(_sub_text_eq, content)
+    content = _TEXT_PSEUDO_RE.sub(_sub_text_pseudo, content)
+    content = _PLACEHOLDER_RE.sub(_sub_placeholder, content)
+    content = _ARIA_LABEL_RE.sub(_sub_aria_label, content)
+    content = _ROLE_RE.sub(_sub_role, content)
+    content = _XPATH_RE.sub(_flag_xpath, content)
+    content = _COMPLEX_CSS_RE.sub(_flag_complex, content)
+
+    return content, changes, todo_count