@qa-gentic/stlc-agents 1.0.26 → 1.0.28

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

@@ -0,0 +1,328 @@
+"""
+Transform plain-string locator files into the agent-friendly format.
+
+Input (migrated raw format):
+  export const dashboardLocators = {
+    userAvatarButton: "navbar_avatar-btn",
+    saveButton:        'button.save-button',
+  };
+
+Output (agent-friendly):
+  export const dashboardLocators = {
+    userAvatarButton: { selector: "navbar_avatar-btn",   intent: "user avatar button",   stability: 80 },
+    saveButton:        { selector: "button.save-button", intent: "save button",           stability: 30 },
+  } as const;
+  export type DashboardLocatorKey = keyof typeof dashboardLocators;
+
+Arrow-function / method-shorthand entries are kept unchanged because they
+produce dynamic selectors that cannot be statically registered.
+
+Text-only values (display strings, URLs, error messages) are also kept as-is.
+"""
+from __future__ import annotations
+import re
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _camel_to_words(name: str) -> str:
+    """userAvatarButton → 'user avatar button'."""
+    s = re.sub(r"([A-Z])", r" \1", name)
+    return s.strip().lower()
+
+
+def _infer_stability(selector: str) -> int:
+    """Assign a 0-100 confidence score based on selector robustness."""
+    if "[data-testid" in selector or "data-testid=" in selector:
+        return 100
+    if selector.startswith("#"):
+        return 80
+    # Bare test-id strings: alphanumeric + hyphens/underscores only (no CSS operators)
+    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
+
+
+def _is_pure_selector(value: str) -> bool:
+    """
+    Return True only for values that look like CSS / test-id selectors.
+    Excludes: URLs, plain text labels, error messages.
+    """
+    if value.startswith("http://") or value.startswith("https://"):
+        return False
+    # Contains a space AND no CSS-selector chars → probably display text
+    if " " in value and not any(c in value for c in "#.[>+~:=*^$|@(\"'"):
+        return False
+    return True
+
+
+def _quote(value: str, original_quote: str) -> str:
+    """Pick inner quote avoiding the same char that appears in value."""
+    if '"' in value and "'" not in value:
+        return "'"
+    if "'" in value and '"' not in value:
+        return '"'
+    # Prefer double-quotes; escape would be needed only if value has both — rare.
+    return '"'
+
+
+# ---------------------------------------------------------------------------
+# Per-object body transformer
+# ---------------------------------------------------------------------------
+
+def _transform_body(block_name: str, body: str) -> tuple[str, list[str]]:
+    """
+    Transform the body text (content between the outer { }) of a locator object.
+    Returns (transformed_body, list_of_change_descriptions).
+    """
+    changes: list[str] = []
+    lines = body.split("\n")
+    result: list[str] = []
+    i = 0
+
+    while i < len(lines):
+        raw = lines[i]
+        stripped = raw.rstrip()
+
+        # ── Pattern 1: single-line string property ──────────────────────────
+        # `  key: "value",` or `  key: 'value',`
+        m1 = re.match(r"^( {2,})(\w+)\s*:\s*(['\"])(.*?)\3,?\s*$", stripped)
+        if m1:
+            indent, key, q, value = m1.group(1), m1.group(2), m1.group(3), m1.group(4)
+            if _is_pure_selector(value):
+                intent    = _camel_to_words(key)
+                stability = _infer_stability(value)
+                iq        = _quote(value, q)
+                result.append(
+                    f"{indent}{key}: {{ selector: {iq}{value}{iq},"
+                    f' intent: "{intent}", stability: {stability} }},'
+                )
+                changes.append(f"Registered locator: {block_name}.{key}")
+                i += 1
+                continue
+
+        # ── Pattern 2: multi-line string property ────────────────────────────
+        # `  key:\n    "value",`
+        m2 = re.match(r"^( {2,})(\w+)\s*:\s*$", stripped)
+        if m2 and (i + 1) < len(lines):
+            next_line = lines[i + 1].strip()
+            mval = re.match(r"^(['\"])(.*?)\1,?\s*$", next_line)
+            if mval:
+                indent, key = m2.group(1), m2.group(2)
+                q, value    = mval.group(1), mval.group(2)
+                if _is_pure_selector(value):
+                    intent    = _camel_to_words(key)
+                    stability = _infer_stability(value)
+                    iq        = _quote(value, q)
+                    result.append(
+                        f"{indent}{key}: {{ selector: {iq}{value}{iq},"
+                        f' intent: "{intent}", stability: {stability} }},'
+                    )
+                    changes.append(f"Registered multi-line locator: {block_name}.{key}")
+                    i += 2
+                    continue
+
+            # ── Pattern 3: multi-line string-concat property ─────────────────
+            # ```
+            #   key:
+            #     "a" +
+            #     "b" +
+            #     "c",
+            # ```
+            # Collect adjacent quoted strings joined by `+` until we hit the
+            # entry's trailing comma. Emits one `{ selector: "a" + "b" + "c",
+            # intent, stability }` entry. Stability is computed from the
+            # concatenated string so multi-line selectors get the same score
+            # they'd receive if written on one line.
+            indent, key = m2.group(1), m2.group(2)
+            concat_re = re.compile(r"^(['\"])(.*?)\1\s*(\+)?\s*$")
+            parts: list[tuple[str, str]] = []  # (quote, value)
+            j = i + 1
+            done = False
+            while j < len(lines):
+                seg = lines[j].strip().rstrip(",")
+                terminates_here = lines[j].rstrip().endswith(",")
+                seg_m = concat_re.match(seg)
+                if not seg_m:
+                    break
+                parts.append((seg_m.group(1), seg_m.group(2)))
+                j += 1
+                if terminates_here:
+                    done = True
+                    break
+            if done and len(parts) >= 2:
+                joined_value = "".join(p[1] for p in parts)
+                if _is_pure_selector(joined_value):
+                    intent    = _camel_to_words(key)
+                    stability = _infer_stability(joined_value)
+                    # Preserve the original quoted-string form so authors keep
+                    # their choice of quote and line-by-line layout signal —
+                    # the runtime concatenation is identical.
+                    rendered  = " + ".join(f"{q}{v}{q}" for q, v in parts)
+                    result.append(
+                        f"{indent}{key}: {{ selector: {rendered},"
+                        f' intent: "{intent}", stability: {stability} }},'
+                    )
+                    changes.append(f"Registered concat locator: {block_name}.{key}")
+                    i = j
+                    continue
+
+        result.append(raw)
+        i += 1
+
+    return "\n".join(result), changes
+
+
+# ---------------------------------------------------------------------------
+# File-level transformer
+# ---------------------------------------------------------------------------
+
+# Matches the opening of a locator constant:
+#   export const xxxLocators = {
+_BLOCK_OPEN_RE = re.compile(
+    r"(export\s+const\s+(\w+Locators)\s*=\s*\{)[ \t]*\n",
+    re.MULTILINE,
+)
+
+# After transformation we append:  } as const;\nexport type ...
+_AS_CONST_RE    = re.compile(r"\}\s*;?\s*$")
+_TYPE_EXPORT_RE = re.compile(r"export type \w+LocatorKey = keyof typeof \w+Locators;")
+
+
+def transform_locator_file(content: str) -> tuple[str, list[str]]:
+    """
+    Transform all locator-constant blocks in a file.
+    Returns (transformed_content, changes).
+    """
+    if "selector:" in content and "intent:" in content:
+        # Already in agent-friendly format — idempotent
+        return content, []
+
+    all_changes: list[str] = []
+    output_parts: list[str] = []
+    cursor = 0
+
+    for m in _BLOCK_OPEN_RE.finditer(content):
+        block_start = m.start()
+        body_start  = m.end()        # first char after the opening `{\n`
+        block_name  = m.group(2)
+
+        # Find the matching closing brace with depth counting
+        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]   # exclude the final `}`
+        suffix = content[j - 1 :]               # `}...` to end (or next block)
+
+        # Transform the body
+        new_body, changes = _transform_body(block_name, body)
+        all_changes.extend(changes)
+
+        # Build a pascal-case type name: dashboardLocators → Dashboard
+        pascal = block_name[0].upper() + block_name[1:]
+        pascal = pascal.replace("Locators", "")
+        type_line = f"export type {pascal}LocatorKey = keyof typeof {block_name};"
+
+        # Everything before this block
+        output_parts.append(content[cursor:block_start])
+
+        # Reconstructed block
+        output_parts.append(m.group(1) + "\n")    # `export const xxx = {`
+        output_parts.append(new_body)
+        # Close: `} as const;`
+        output_parts.append("} as const;\n")
+        if changes:  # only add type export if we actually transformed something
+            output_parts.append(type_line + "\n")
+
+        # Skip over the original closing `};` in suffix
+        # suffix starts with `}` — find the end of `};` or `}`
+        tail_m = re.match(r"\}\s*;?\s*\n?", suffix)
+        tail_skip = tail_m.end() if tail_m else 1
+        cursor = j - 1 + tail_skip
+
+    # Append remaining file content (after last block)
+    output_parts.append(content[cursor:])
+
+    return "".join(output_parts), all_changes
+
+
+# ---------------------------------------------------------------------------
+# Post-migration: fix selector accesses in page objects / step files
+# ---------------------------------------------------------------------------
+
+def collect_object_keys(locator_file_content: str) -> dict[str, set[str]]:
+    """
+    Parse an already-transformed locator file and return a mapping of
+    { locator_name → set_of_keys_that_are_objects }.
+
+    Only keys with `{ selector: ... }` values are object-valued.
+    String-valued keys (display text, URLs) are excluded.
+    """
+    result: dict[str, set[str]] = {}
+    _OBJ_KEY_RE = re.compile(r"^\s{2,}(\w+)\s*:\s*\{[^}]*selector:", re.MULTILINE)
+
+    for m_block in _BLOCK_OPEN_RE.finditer(locator_file_content):
+        block_name = m_block.group(2)
+        body_start = m_block.end()
+        depth = 1
+        j = body_start
+        while j < len(locator_file_content) and depth > 0:
+            c = locator_file_content[j]
+            if c == "{":
+                depth += 1
+            elif c == "}":
+                depth -= 1
+            j += 1
+        body = locator_file_content[body_start : j - 1]
+        object_keys = {km.group(1) for km in _OBJ_KEY_RE.finditer(body)}
+        result[block_name] = object_keys
+
+    return result
+
+
+def fix_selector_accesses(
+    content: str,
+    object_keys_by_name: dict[str, set[str]],
+) -> tuple[str, list[str]]:
+    """
+    In a page-object / step file, rewrite `xxxLocators.key` → `xxxLocators.key.selector`
+    for every key that is now a structured object `{ selector, intent, stability }`.
+
+    Leaves:
+      - string-valued keys unchanged (display text, URLs)
+      - function-call entries unchanged: xxxLocators.fn(arg)
+      - already-fixed accesses: xxxLocators.key.selector
+    """
+    changes: list[str] = []
+    for loc_name, obj_keys in object_keys_by_name.items():
+        if not obj_keys:
+            continue
+        # Build alternation of all object keys for this locator group
+        keys_alt = "|".join(re.escape(k) for k in sorted(obj_keys, key=len, reverse=True))
+        pattern = re.compile(
+            rf"\b({re.escape(loc_name)})\.({keys_alt})\b"
+            r"(?!\.(?:selector|intent|stability))"   # not already .selector/.intent/.stability
+            r"(?!\s*\()",                             # not a function call
+        )
+
+        def _replace(m: re.Match, ln=loc_name) -> str:
+            changes.append(f"Added .selector: {m.group(0)}")
+            return f"{m.group(1)}.{m.group(2)}.selector"
+
+        content = pattern.sub(_replace, content)
+    return content, changes