@qa-gentic/stlc-agents 1.0.26 → 1.0.28

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

@@ -0,0 +1,1143 @@
+"""
+Inject TimingHealer and VisualIntentChecker into migrated Playwright code.
+
+Scope: ALL Playwright interactions — page objects, step definitions, and
+       any helper file that contains raw page.click / page.fill calls.
+"""
+from __future__ import annotations
+import re
+
+_HEALER_IMPORTS = """\
+import { createLogger, transports } from 'winston';
+import { LocatorHealer } from '@utils/locators/LocatorHealer';
+import { LocatorRepository } from '@utils/locators/LocatorRepository';
+import { TimingHealer } from '@utils/locators/TimingHealer';
+import { VisualIntentChecker } from '@utils/locators/VisualIntentChecker';\
+"""
+
+# Private field declarations injected after the class opening brace (page objects)
+# _repo is a field initializer (no this.page needed); healers are assigned in ctor
+_HEALER_FIELDS = (
+    "  private _repo    = new LocatorRepository();\n"
+    "  private _logger  = createLogger({ transports: [new transports.Console()] });\n"
+    "  private _healer!: LocatorHealer;\n"
+    "  private _timing!: TimingHealer;\n"
+    "  private _visual!: VisualIntentChecker;\n"
+)
+
+# Assignments injected in the constructor body (after super() if present).
+# {registrations} is replaced with locator registration calls when locator imports are detected.
+_HEALER_CTOR_ASSIGN = (
+    "\n    this._healer = new LocatorHealer(this.page, this._logger, this._repo);\n"
+    "    this._timing  = new TimingHealer(this.page, this._logger, this._repo);\n"
+    "    this._visual  = new VisualIntentChecker(this.page, this._logger, this._repo);\n"
+    "{registrations}"
+)
+
+# Detect `import { xxxLocators[, ...] } from '@locators/...'`
+_LOCATOR_IMPORT_RE = re.compile(
+    r"import\s+\{([^}]+)\}\s+from\s+['\"]@locators/[^'\"]+['\"]"
+)
+
+# Healer setup for `function ()` step callbacks — `this` binds to Cucumber's World.
+# `this.page!` definite-assignment assertion: World's type doesn't declare `page` in strict mode.
+_STEP_HEALER_SETUP = (
+    "\n    const _repo    = new LocatorRepository();\n"
+    "    const _logger  = createLogger({ transports: [new transports.Console()] });\n"
+    "    const _healer  = new LocatorHealer(this.page!, _logger, _repo);\n"
+    "    const _timing  = new TimingHealer(this.page!, _logger, _repo);\n"
+    "    const _visual  = new VisualIntentChecker(this.page!, _logger, _repo);\n"
+)
+
+# Healer setup for `async () => {}` arrow step callbacks — no `this` binding,
+# so we get the page via fixture() instead.
+_STEP_ARROW_HEALER_SETUP = (
+    "\n    const _repo    = new LocatorRepository();\n"
+    "    const _logger  = createLogger({ transports: [new transports.Console()] });\n"
+    "    const _page    = fixture().page;\n"
+    "    const _healer  = new LocatorHealer(_page, _logger, _repo);\n"
+    "    const _timing  = new TimingHealer(_page, _logger, _repo);\n"
+    "    const _visual  = new VisualIntentChecker(_page, _logger, _repo);\n"
+)
+
+# Receivers for `<X>.click(...)` etc.
+#   • `page` / `this.page` / `world.page` / `ctx.page` — direct
+#   • `currentFixture.page` / `this.currentFixture.page` — common QA fixture
+# Anything else (e.g. raw `popup.click`) stays untouched.
+_PAGE_EXPR   = r"(?:(?:this|world|ctx)\s*\.\s*)?(?:currentFixture\s*\.\s*)?page"
+
+# `await` is optional: Playwright actions also appear unawaited inside
+# `Promise.all([...])` blocks (the await is on the surrounding Promise.all).
+# Allowing optional await covers both forms without inventing matches —
+# the rest of the pattern still requires the exact `<receiver>.<verb>(...)`
+# shape so we don't grab unrelated method calls.
+_AWAIT_OPT   = r"(?:await\s+)?"
+
+_CLICK_RE    = re.compile(rf"{_AWAIT_OPT}{_PAGE_EXPR}\s*\.\s*click\(\s*([^)]+)\s*\)")
+_FILL_RE     = re.compile(rf"{_AWAIT_OPT}{_PAGE_EXPR}\s*\.\s*fill\(\s*([^,)]+)\s*,\s*([^)]+)\s*\)")
+_CHECK_RE    = re.compile(rf"{_AWAIT_OPT}{_PAGE_EXPR}\s*\.\s*check\(\s*([^)]+)\s*\)")
+_UNCHECK_RE  = re.compile(rf"{_AWAIT_OPT}{_PAGE_EXPR}\s*\.\s*uncheck\(\s*([^)]+)\s*\)")
+_SELECT_RE   = re.compile(rf"{_AWAIT_OPT}{_PAGE_EXPR}\s*\.\s*selectOption\(\s*([^,)]+)\s*,\s*([^)]+)\s*\)")
+_GOTO_RE     = re.compile(rf"await\s+({_PAGE_EXPR})\s*\.\s*goto\(\s*([^)]+)\s*\)")
+_EXPECT_VISIBLE_RE = re.compile(r"await\s+expect\(([^)]+)\)\s*\.\s*toBeVisible\([^)]*\)")
+
+_counter: list[int] = [0]
+
+
+def _next_key(prefix: str) -> str:
+    _counter[0] += 1
+    return f"{prefix}{_counter[0]}"
+
+
+def _build_locator_registrations(content: str) -> str:
+    """
+    Scan the file for `import { xxxLocators } from '@locators/...'` statements
+    and build constructor registration calls so the LocatorRepository is populated.
+
+    For each imported locator object (xxxLocators), each entry is registered
+    under BOTH key shapes so callers using either convention resolve:
+
+      • Namespaced:  `xxxPage.<key>`   (emitted by this migration's healer rewriter)
+      • Bare:        `<key>`           (emitted by older migration tools / hand-written code)
+
+    Older migrated trees frequently have a mix — the rewriter touched some
+    `page.click(...)` sites and converted them to `_healer.clickWithHealing('xxx.key', ...)`
+    while leaving pre-existing `_healer.fillWithHealing("key", ...)` calls
+    untouched. Registering both shapes means neither convention silently
+    no-ops on `updateHealed` (the early-return on `store.get(key) === undefined`).
+
+    Only emitted when the locator file has already been converted to the
+    { selector, intent, stability } format by locator_registrar.
+    """
+    registrations: list[str] = []
+    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")]
+        for name in names:
+            # Derive a namespace prefix: dashboardLocators → "dashboard"
+            ns = name[0].lower() + name[1:]
+            ns = ns.replace("Locators", "")
+            registrations.append(
+                f"    Object.entries({name}).forEach(([key, val]) => {{\n"
+                f"      if (typeof val === 'object' && val !== null && 'selector' in val) {{\n"
+                f"        this._repo.register(`{ns}.${{key}}`, "
+                f"(val as any).selector, (val as any).intent, (val as any).stability ?? 0);\n"
+                f"        // Bare-key alias for legacy call sites that didn't namespace the key.\n"
+                f"        this._repo.register(key, "
+                f"(val as any).selector, (val as any).intent, (val as any).stability ?? 0);\n"
+                f"      }}\n"
+                f"    }});\n"
+            )
+    return "".join(registrations)
+
+
+def _ensure_locator_registrations(content: str, changes: list[str]) -> str:
+    """
+    Patch a *page-object* file that already has the healer scaffolded (imports
+    + private fields + ctor assignments) but is missing the per-key
+    `this._repo.register(...)` calls that populate the in-memory store.
+
+    Without these calls every `updateHealed(...)` invocation finds no entry
+    for its key, returns early, and the heal store JSON is never written —
+    the symptom that surfaced on re-migration runs.
+
+    Idempotent: if `this._repo.register(` already appears anywhere in the
+    file, no change is made.
+    """
+    if "this._repo.register(" in content:
+        return content
+    registrations = _build_locator_registrations(content)
+    if not registrations:
+        return content
+    # Anchor on the `this._healer = new LocatorHealer(...)` assignment the
+    # previous migration emitted. Insert the registrations right after the
+    # full healer/timing/visual triple (after the line containing
+    # `new VisualIntentChecker(`). Fall back to inserting right after
+    # `new LocatorHealer(` if the visual line isn't present.
+    anchors = [
+        r"this\._visual\s*=\s*new\s+VisualIntentChecker\([^)]*\);[^\n]*\n",
+        r"this\._timing\s*=\s*new\s+TimingHealer\([^)]*\);[^\n]*\n",
+        r"this\._healer\s*=\s*new\s+LocatorHealer\([^)]*\);[^\n]*\n",
+    ]
+    for pat in anchors:
+        m = re.search(pat, content)
+        if m:
+            content = content[: m.end()] + registrations + content[m.end():]
+            changes.append("Injected missing this._repo.register() calls (re-migration patch)")
+            return content
+    return content
+
+
+def inject_healers(
+    content: str,
+    role: str,
+    object_keys: dict[str, set[str]] | None = None,
+) -> tuple[str, list[str], int]:
+    """
+    Inject healer wrappers.
+
+    role: "page_object" | "step_def" | anything else (generic).
+    object_keys: optional map of `xxxLocators` name -> set of keys that are
+        object-valued ({selector, intent, stability}). Used to skip healing
+        wraps for string-valued display labels (e.g. `myBundleText: "My Bundle"`)
+        which would otherwise produce `.selector` accesses on a plain string.
+        When None, every locator reference is treated as object-valued (legacy
+        behavior — safe for callers that haven't been updated).
+    Returns (transformed_content, changes, todo_count).
+    """
+    _counter[0] = 0
+    changes: list[str] = []
+    todo_count = 0
+
+    # Detect re-migration: a file where a previous pass already wired up the
+    # healer's runtime objects (fields for page objects, const setup for step
+    # callbacks). We check for the actual assignments — `new LocatorHealer(`
+    # or `clickWithHealing(` — NOT just the import line, because an import
+    # alone doesn't establish `_healer` / `_timing` / `_visual` in scope.
+    # Misclassifying an import-only file as "already injected" caused the
+    # setup pass to be skipped and the rewriter to reference undefined
+    # `_timing` / `_visual` symbols in step callbacks.
+    already_injected = (
+        "new LocatorHealer(" in content
+        or "clickWithHealing(" in content
+        or "fillWithHealing(" in content
+        or "assertVisibleWithHealing(" in content
+    )
+
+    if not already_injected:
+        content = _prepend_imports(content, changes)
+
+    if role == "page_object":
+        if already_injected:
+            # The healer fields and ctor assignments exist but a previous
+            # migration pass may not have emitted the locator registrations.
+            # Without them every key passed to `updateHealed` is unknown to
+            # the in-memory store and the heal write silently no-ops. Patch
+            # in the registrations before the action rewriter runs.
+            content = _ensure_locator_registrations(content, changes)
+            content = _replace_actions(
+                content, changes, prefix="po", use_this=True, object_keys=object_keys,
+            )
+        else:
+            content = _inject_page_object(content, changes, object_keys)
+    elif role == "step_def":
+        if already_injected:
+            content = _replace_actions(
+                content, changes, prefix="step", use_this=False, object_keys=object_keys,
+            )
+        else:
+            content = _inject_step_defs(content, changes, object_keys)
+    else:
+        if already_injected:
+            content = _replace_actions(
+                content, changes, prefix="gen", use_this=False, object_keys=object_keys,
+            )
+        else:
+            content, todo_count = _inject_generic(content, changes, object_keys)
+
+    return content, changes, todo_count
+
+
+# ---------------------------------------------------------------------------
+# Import injection
+# ---------------------------------------------------------------------------
+
+def _prepend_imports(content: str, changes: list[str]) -> str:
+    if "LocatorHealer" in content:
+        return content
+
+    lines = content.split("\n")
+    # Find the last complete import / require statement.
+    # Multi-line imports like `import {\n  Foo,\n} from '...'` must be tracked
+    # so we insert AFTER the closing `} from '...'` line, not inside the braces.
+    last_import = -1
+    in_multiline = False
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        if in_multiline:
+            # Wait for the closing `} from '...'` line
+            if re.match(r"^\}\s*from\s+['\"]", stripped):
+                last_import = i
+                in_multiline = False
+            continue
+        if stripped.startswith("import ") and stripped.endswith("{") and "from" not in stripped:
+            # Opening of a multi-line import: `import {` or `import Foo, {`
+            in_multiline = True
+            continue
+        if stripped.startswith("import "):
+            last_import = i
+        # Only match top-level require() — NOT indented ones inside class methods
+        elif line.startswith("const ") and "require" in line:
+            last_import = i
+
+    insert_at = last_import + 1 if last_import >= 0 else 0
+    lines.insert(insert_at, _HEALER_IMPORTS)
+    changes.append("Injected healer imports")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Page-object injection
+# ---------------------------------------------------------------------------
+
+def _inject_page_object(content: str, changes: list[str], object_keys: dict[str, set[str]] | None = None) -> str:
+    # Step A: inject private field declarations right after the class opening brace.
+    class_body_re = re.compile(
+        r"(class\s+\w+(?:\s+extends\s+[\w.<>,\s]+)?\s*\{)[ \t]*\n",
+        re.MULTILINE,
+    )
+    m_cls = class_body_re.search(content)
+    if m_cls:
+        content = content[: m_cls.end()] + _HEALER_FIELDS + content[m_cls.end() :]
+        changes.append("Injected healer field declarations into class body")
+
+    # Build locator registration lines for any imported locator objects
+    registrations = _build_locator_registrations(content)
+    ctor_assign    = _HEALER_CTOR_ASSIGN.replace("{registrations}", registrations)
+    if registrations:
+        changes.append("Injected LocatorRepository.register() calls for imported locators")
+
+    # Step B: inject constructor assignments.
+    # 1. Constructor with super() — inject after super()
+    ctor_super_re = re.compile(
+        r"(constructor\s*\([^)]*\)\s*\{[^}]*?super\s*\([^)]*\)\s*;?)",
+        re.DOTALL,
+    )
+    m = ctor_super_re.search(content)
+    if m:
+        content = content[: m.end()] + ctor_assign + content[m.end() :]
+        changes.append("Injected healer assignments into constructor (after super)")
+    else:
+        # 2. Constructor without super() — inject at start of constructor body
+        ctor_re = re.compile(r"(constructor\s*\([^)]*\)\s*\{[ \t]*\n)", re.MULTILINE)
+        m2 = ctor_re.search(content)
+        if m2:
+            content = content[: m2.end()] + ctor_assign + content[m2.end() :]
+            changes.append("Injected healer assignments into constructor")
+        else:
+            changes.append("No constructor found — healer fields declared; add ctor to init them")
+
+    # Step C: replace raw Playwright actions with this._healer calls
+    content = _replace_actions(content, changes, prefix="po", use_this=True, object_keys=object_keys)
+    return content
+
+
+# ---------------------------------------------------------------------------
+# Step-definition injection
+# ---------------------------------------------------------------------------
+
+def _inject_step_defs(content: str, changes: list[str], object_keys: dict[str, set[str]] | None = None) -> str:
+    # Inject healer setup at the start of each step callback. The callback
+    # can take several syntactic forms — all of which must be matched:
+    #
+    #   When("...", async function () { ... })
+    #   When("...", async function (): Promise<void> { ... })   ← TS return type
+    #   When(
+    #     "...",
+    #     async function (): Promise<void> { ... }              ← multi-line wrap
+    #   )
+    #   When("...", async ({ page }) => { ... })                ← arrow
+    #
+    # The leading-string match `[^,]+?` is non-greedy to keep us from sliding
+    # past a comma inside the step name when scenarios accidentally include
+    # commas in their text (rare, but it has happened).
+    step_fn_re = re.compile(
+        r"((?:Given|When|Then|And|But)\s*\(\s*[^,]+?,\s*"
+        r"async\s+function\s*\([^)]*\)"
+        r"(?:\s*:\s*[^{}]+?)?"          # optional `: Promise<void>` return type
+        r"\s*\{)",
+        re.DOTALL,
+    )
+
+    def _inject(m: re.Match) -> str:
+        changes.append("Injected healer setup into step function")
+        return m.group(0) + _STEP_HEALER_SETUP
+
+    content = step_fn_re.sub(_inject, content)
+
+    # Arrow-function callbacks
+    arrow_re = re.compile(
+        r"((?:Given|When|Then|And|But)\s*\(\s*[^,]+?,\s*"
+        r"async\s*\([^)]*\)"
+        r"(?:\s*:\s*[^{}=]+?)?"        # optional return-type annotation
+        r"\s*=>\s*\{)"
+    )
+
+    def _inject_arrow(m: re.Match) -> str:
+        changes.append("Injected healer setup into arrow step function")
+        return m.group(0) + _STEP_ARROW_HEALER_SETUP
+
+    content = arrow_re.sub(_inject_arrow, content)
+
+    content = _replace_actions(content, changes, prefix="step", object_keys=object_keys)
+    return content
+
+
+# ---------------------------------------------------------------------------
+# Generic injection
+# ---------------------------------------------------------------------------
+
+def _inject_generic(content: str, changes: list[str], object_keys: dict[str, set[str]] | None = None) -> tuple[str, int]:
+    has_actions = bool(
+        _CLICK_RE.search(content)
+        or _FILL_RE.search(content)
+        or _CHECK_RE.search(content)
+    )
+    if not has_actions:
+        return content, 0
+
+    todo_line = "// TODO: initialize healers — const _repo = new LocatorRepository(); const _healer = new LocatorHealer(page, _repo);\n"
+    content   = todo_line + content
+    content   = _replace_actions(content, changes, prefix="gen", object_keys=object_keys)
+    changes.append("Generic healer injection applied (see TODO comment)")
+    return content, 1
+
+
+# ---------------------------------------------------------------------------
+# Shared action replacement
+# ---------------------------------------------------------------------------
+
+def _balanced(s: str) -> bool:
+    """Return True if parentheses in s are balanced (no unclosed subexpressions)."""
+    depth = 0
+    for ch in s:
+        if ch == "(":
+            depth += 1
+        elif ch == ")":
+            depth -= 1
+            if depth < 0:
+                return False
+    return depth == 0
+
+
+def _extract_call_args(text: str, paren_idx: int) -> tuple[list[str], int] | None:
+    """
+    Given `text` and an index pointing at `(`, return `(args, end_idx)`
+    where `args` is the list of comma-separated top-level arguments
+    (stripped) and `end_idx` is one past the matching `)`.
+
+    Respects nested parens, brackets, braces, single/double quoted strings,
+    and template literals. Returns None if the call is unbalanced.
+    """
+    if paren_idx >= len(text) or text[paren_idx] != "(":
+        return None
+    depth = 1
+    i = paren_idx + 1
+    arg_start = i
+    args: list[str] = []
+    in_str: str | None = None
+    n = len(text)
+    while i < n:
+        c = text[i]
+        if in_str:
+            if c == "\\" and i + 1 < n:
+                i += 2
+                continue
+            if c == in_str:
+                in_str = None
+            i += 1
+            continue
+        if c in ('"', "'", "`"):
+            in_str = c
+            i += 1
+            continue
+        if c in "([{":
+            depth += 1
+        elif c in ")]}":
+            depth -= 1
+            if depth == 0:
+                tail = text[arg_start:i].strip()
+                # Append only non-empty trailing args. A trailing comma
+                # (`fill(a, b,)`) is common in multi-line formatting; we
+                # treat it as 2 args, not 3.
+                if tail:
+                    args.append(tail)
+                return args, i + 1
+        elif c == "," and depth == 1:
+            args.append(text[arg_start:i].strip())
+            arg_start = i + 1
+        i += 1
+    return None
+
+
+def _scan_and_rewrite(
+    content: str,
+    prefix_re: re.Pattern,
+    rewrite_args: callable,
+) -> str:
+    """
+    Find each match of `prefix_re` (a regex whose final char-class is `(`).
+    For each, extract the balanced argument list via _extract_call_args and
+    delegate to `rewrite_args(prefix_text, args)` to build the replacement.
+
+    `rewrite_args` returns the replacement string, or None to leave the
+    original call intact.
+    """
+    out: list[str] = []
+    last = 0
+    for m in prefix_re.finditer(content):
+        # prefix_re ends with `\(` — locate that paren in the matched text.
+        paren_idx = content.find("(", m.start(), m.end())
+        if paren_idx < 0:
+            continue
+        result = _extract_call_args(content, paren_idx)
+        if result is None:
+            continue
+        args, end_idx = result
+        replacement = rewrite_args(m.group(0)[: paren_idx - m.start()], args)
+        out.append(content[last : m.start()])
+        if replacement is None:
+            out.append(content[m.start() : end_idx])
+        else:
+            out.append(replacement)
+        last = end_idx
+    out.append(content[last:])
+    return "".join(out)
+
+
+# Detect `xxxLocators.yyy` accesses (NOT followed by `(` → not a function call).
+# This lets us derive a stable, semantic healing key from the locator itself
+# instead of using an auto-generated counter like `po_vis1`.
+_LOCATOR_ACCESS_RE = re.compile(r"\b(\w+Locators)\.(\w+)\b(?!\s*\()")
+
+# Detect local variable assignments whose RHS references a locator-repo entry.
+# Matches: `const x = ...`, `let x = ...`, `private x = ...`, `private readonly x = ...`, etc.
+# DOTALL so multi-line RHS like `this.page.locator(\n  fooLocators.bar.selector,\n)` 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*(.+?);",
+    re.DOTALL,
+)
+
+# Detect chained-locator calls on a bare identifier: `await <var>.click()` / `.fill(...)`.
+# The negative lookahead skips `page.`, `this.`, `world.`, `ctx.` so it doesn't shadow _CLICK_RE.
+_CHAINED_CLICK_RE = re.compile(
+    r"await\s+(?!page\b|this\b|world\b|ctx\b)(\w+)\s*\.\s*click\(\s*\)"
+)
+_CHAINED_FILL_RE = re.compile(
+    r"await\s+(?!page\b|this\b|world\b|ctx\b)(\w+)\s*\.\s*fill\(\s*([^)]+)\s*\)"
+)
+
+# Custom wrappers most QA projects define around Playwright actions — they
+# take a selector string and dispatch to page.click / page.fill. Routing them
+# to the healer instead means *every* call site goes through the healing
+# chain, not just direct page.click() / page.fill() calls.
+#
+# Matches: `base.waitAndClick(X)`, `this.base.waitAndClick(X)`,
+#          `base.waitAndClickByTestId(X)`, `this.base.waitAndClickByTestId(X)`
+_WRAPPER_CLICK_RE = re.compile(
+    rf"{_AWAIT_OPT}(?:this\s*\.\s*)?base\s*\.\s*waitAndClick(?:ByTestId)?\(\s*([^)]+)\s*\)"
+)
+_WRAPPER_FILL_RE = re.compile(
+    rf"{_AWAIT_OPT}(?:this\s*\.\s*)?base\s*\.\s*waitAndFill(?:ByTestId)?\(\s*([^,]+)\s*,\s*([^)]+)\s*\)"
+)
+
+# Chained .locator(X).click() / .fill(X, v) — only when there are no
+# intermediate filter calls (.first(), .nth(), .filter()) that would change
+# the selector's semantics. The healer takes a raw selector string and
+# handles filtering itself, so wrapping these is safe; chains with filters
+# stay as raw Playwright since their semantics aren't reducible to a key.
+_LOC_CHAIN_CLICK_RE = re.compile(
+    rf"{_AWAIT_OPT}{_PAGE_EXPR}\s*\.\s*locator\(\s*([^)]+?)\s*\)\.click\(\s*\)"
+)
+_LOC_CHAIN_FILL_RE = re.compile(
+    rf"{_AWAIT_OPT}{_PAGE_EXPR}\s*\.\s*locator\(\s*([^)]+?)\s*\)\.fill\(\s*([^)]+)\s*\)"
+)
+
+
+def _semantic_for(
+    loc_name: str,
+    prop: str,
+    object_keys: dict[str, set[str]] | None,
+) -> tuple[str, str, str] | None:
+    """Build (key, intent_expr, selector_expr) for a recognised locator ref."""
+    if object_keys is not None and prop not in object_keys.get(loc_name, set()):
+        return None
+    namespace   = loc_name[0].lower() + loc_name[1:]
+    namespace   = namespace.replace("Locators", "")
+    return (
+        f"{namespace}.{prop}",
+        f"{loc_name}.{prop}.intent",
+        f"{loc_name}.{prop}.selector",
+    )
+
+
+def _derive_semantic(
+    expr: str,
+    object_keys: dict[str, set[str]] | None = None,
+    alias_map: dict[str, str] | None = None,
+    inline_field_map: dict[tuple[str, str], tuple[str, str]] | None = None,
+) -> tuple[str, str, str] | None:
+    """
+    If `expr` contains a recognised locator reference, return:
+      (healing_key, intent_expr, selector_expr)
+
+    Recognised forms:
+      • Direct:        `xxxLocators.yyy`               (with or without `.selector`)
+      • Aliased:       `this.Elements.yyy` / `E.yyy`   (via _collect_alias_map)
+      • Inline field:  `this.MassInviteElements.yyy`   (via _collect_inline_field_map)
+
+    When `object_keys` is provided, only keys that are object-valued
+    ({selector, intent, stability}) qualify. String-valued display labels
+    return None so the call stays raw instead of producing a `.selector`
+    access on a plain string.
+
+    Returns None when no qualifying locator access is found.
+    """
+    # 1. Direct: xxxLocators.prop  (optionally followed by .selector)
+    for m in _LOCATOR_ACCESS_RE.finditer(expr):
+        sem = _semantic_for(m.group(1), m.group(2), object_keys)
+        if sem:
+            return sem
+
+    # 2. Aliased: <alias>.prop  — alias_map carries `this.Elements → xxxLocators`
+    #    Match each alias's access pattern. We iterate longest first so a
+    #    longer alias like `this.Elements` wins over a colliding bare `Elements`.
+    if alias_map:
+        for alias in sorted(alias_map, key=len, reverse=True):
+            loc_name = alias_map[alias]
+            alias_re = re.compile(
+                rf"(?<![.\w]){re.escape(alias)}\.(\w+)\b(?!\s*\()"
+            )
+            for m in alias_re.finditer(expr):
+                sem = _semantic_for(loc_name, m.group(1), object_keys)
+                if sem:
+                    return sem
+
+    # 3. Inline-field re-export: `this.<FieldName>.<inline_key>` whose value
+    #    in the class field is `<xxxLocators>.<orig_key>.selector`. Routes
+    #    the healer call through the ORIGINAL locator's semantic info, but
+    #    keeps the user-facing selector expression as the field reference
+    #    (preserving the runtime string they wrote).
+    if inline_field_map:
+        # Sort aliases longest-first so `this.MassInviteElements` wins over
+        # any colliding shorter alias.
+        aliases = sorted({alias for (alias, _) in inline_field_map}, key=len, reverse=True)
+        for alias in aliases:
+            alias_re = re.compile(
+                rf"(?<![.\w]){re.escape(alias)}\.(\w+)\b(?!\s*\()"
+            )
+            for m in alias_re.finditer(expr):
+                inline_key = m.group(1)
+                mapped = inline_field_map.get((alias, inline_key))
+                if not mapped:
+                    continue
+                loc_name, orig_key = mapped
+                # Build a custom semantic tuple: keep `selector_expr` as the
+                # field reference so the runtime string-typed value passes
+                # straight through to the healer.
+                if object_keys is not None and orig_key not in object_keys.get(loc_name, set()):
+                    continue
+                ns  = loc_name[0].lower() + loc_name[1:]
+                ns  = ns.replace("Locators", "")
+                return (
+                    f"{ns}.{orig_key}",
+                    f"{loc_name}.{orig_key}.intent",
+                    f"{alias}.{inline_key}",
+                )
+    return None
+
+
+_IDENT_RE = re.compile(r"^\w+$")
+
+
+def _build_var_to_semantic(
+    content: str,
+    object_keys: dict[str, set[str]] | None = None,
+    alias_map: dict[str, str] | None = None,
+    inline_field_map: dict[tuple[str, str], tuple[str, str]] | None = None,
+) -> dict[str, tuple[str, str, str]]:
+    """
+    Scan local variable assignments and map each variable name to the semantic
+    key/intent/selector triple derived from the locator-repo entry referenced on
+    its RHS. Skips RHS that only references string-valued locator entries when
+    object_keys is provided.
+    """
+    result: dict[str, tuple[str, str, str]] = {}
+    for m in _VAR_ASSIGN_RE.finditer(content):
+        var_name = m.group(1)
+        rhs = m.group(2)
+        sem = _derive_semantic(rhs, object_keys, alias_map, inline_field_map)
+        if sem:
+            result[var_name] = sem
+    return result
+
+
+def _resolve_semantic(
+    expr: str,
+    var_map: dict[str, tuple[str, str, str]],
+    object_keys: dict[str, set[str]] | None = None,
+    alias_map: dict[str, str] | None = None,
+    inline_field_map: dict[tuple[str, str], tuple[str, str]] | None = None,
+) -> tuple[str, str, str] | None:
+    """Try direct locator-repo access first; fall back to local-variable lookup."""
+    sem = _derive_semantic(expr, object_keys, alias_map, inline_field_map)
+    if sem:
+        return sem
+    if _IDENT_RE.match(expr):
+        return var_map.get(expr)
+    return None
+
+
+def _replace_actions(
+    content: str,
+    changes: list[str],
+    prefix: str,
+    use_this: bool = False,
+    object_keys: dict[str, set[str]] | None = None,
+) -> str:
+    # For page objects, healers are class properties — accessed via this._healer
+    # For step defs and generic, healers are local const variables — accessed directly
+    h = "this._healer" if use_this else "_healer"
+    t = "this._timing"  if use_this else "_timing"
+    v = "this._visual"  if use_this else "_visual"
+
+    # Collect alias + inline-field maps BEFORE the rewrites so wrapper /
+    # action calls that reference `this.Elements.foo`, `this.MassInvite.foo`,
+    # or bare aliased identifiers route through the healer too.
+    alias_map = _collect_alias_map(content)
+    inline_field_map = _collect_inline_field_map(content)
+    var_map = _build_var_to_semantic(content, object_keys, alias_map, inline_field_map)
+
+    # Counter for synthetic keys when a call site uses a runtime-computed
+    # selector (template literal, variable, function-call result, raw
+    # string literal). Routing these through the healer still adds value:
+    # the healer's chain logs failures, retries with role/label/text/AI
+    # strategies, and persists healed selectors to the repository.
+    dyn_counter = [0]
+
+    def _next_dyn_key() -> str:
+        dyn_counter[0] += 1
+        return f"dyn.{prefix}.{dyn_counter[0]}"
+
+    def _intent_for_dyn(sel_expr: str) -> str:
+        """
+        Synthesize an intent string from a dynamic selector expression. Bare
+        identifier → camel-cased to words; everything else → "dynamic locator".
+        The intent feeds the healer's role/label/text fallback heuristics.
+        """
+        stripped = sel_expr.strip()
+        if _IDENT_RE.match(stripped):
+            spaced = re.sub(r"([A-Z])", r" \1", stripped).strip().lower()
+            spaced = re.sub(r"selector\b", "", spaced).strip() or stripped
+            return f'"{spaced}"'
+        return '"dynamic locator"'
+
+    def _click(m: re.Match) -> str:
+        sel = m.group(1).strip().rstrip(",").strip()
+        if not _balanced(sel):
+            return m.group(0)
+        semantic = _resolve_semantic(sel, var_map, object_keys, alias_map, inline_field_map)
+        if semantic:
+            key, intent_expr, sel_expr = semantic
+            changes.append(f"page.click → {h}.clickWithHealing (key={key})")
+            return f"await {h}.clickWithHealing('{key}', {sel_expr}, {intent_expr})"
+        # Dynamic-selector fallback: synthesise a key and use the original
+        # expression as both selector and intent source.
+        key = _next_dyn_key()
+        changes.append(f"page.click → {h}.clickWithHealing (dyn key={key})")
+        return f"await {h}.clickWithHealing('{key}', {sel}, {_intent_for_dyn(sel)})"
+
+    def _fill(m: re.Match) -> str:
+        sel = m.group(1).strip().rstrip(",").strip()
+        val = m.group(2).strip().rstrip(",").strip()
+        if not _balanced(sel) or not _balanced(val):
+            return m.group(0)
+        semantic = _resolve_semantic(sel, var_map, object_keys, alias_map, inline_field_map)
+        if semantic:
+            key, intent_expr, sel_expr = semantic
+            changes.append(f"page.fill → {h}.fillWithHealing (key={key})")
+            return f"await {h}.fillWithHealing('{key}', {sel_expr}, {val}, {intent_expr})"
+        key = _next_dyn_key()
+        changes.append(f"page.fill → {h}.fillWithHealing (dyn key={key})")
+        return f"await {h}.fillWithHealing('{key}', {sel}, {val}, {_intent_for_dyn(sel)})"
+
+    def _wrapper_click(m: re.Match) -> str:
+        """`base.waitAndClick(X)` / `base.waitAndClickByTestId(X)` → healer."""
+        sel = m.group(1).strip().rstrip(",").strip()
+        if not _balanced(sel):
+            return m.group(0)
+        semantic = _resolve_semantic(sel, var_map, object_keys, alias_map, inline_field_map)
+        if semantic:
+            key, intent_expr, sel_expr = semantic
+            changes.append(f"base.waitAndClick* → {h}.clickWithHealing (key={key})")
+            return f"await {h}.clickWithHealing('{key}', {sel_expr}, {intent_expr})"
+        key = _next_dyn_key()
+        changes.append(f"base.waitAndClick* → {h}.clickWithHealing (dyn key={key})")
+        return f"await {h}.clickWithHealing('{key}', {sel}, {_intent_for_dyn(sel)})"
+
+    def _wrapper_fill(m: re.Match) -> str:
+        """`base.waitAndFill(X, v)` / `base.waitAndFillByTestId(X, v)` → healer."""
+        sel = m.group(1).strip().rstrip(",").strip()
+        val = m.group(2).strip().rstrip(",").strip()
+        if not _balanced(sel) or not _balanced(val):
+            return m.group(0)
+        semantic = _resolve_semantic(sel, var_map, object_keys, alias_map, inline_field_map)
+        if semantic:
+            key, intent_expr, sel_expr = semantic
+            changes.append(f"base.waitAndFill* → {h}.fillWithHealing (key={key})")
+            return f"await {h}.fillWithHealing('{key}', {sel_expr}, {val}, {intent_expr})"
+        key = _next_dyn_key()
+        changes.append(f"base.waitAndFill* → {h}.fillWithHealing (dyn key={key})")
+        return f"await {h}.fillWithHealing('{key}', {sel}, {val}, {_intent_for_dyn(sel)})"
+
+    def _loc_chain_click(m: re.Match) -> str:
+        """`<recv>.locator(X).click()` (no intermediate filters) → healer."""
+        sel = m.group(1).strip().rstrip(",").strip()
+        if not _balanced(sel):
+            return m.group(0)
+        semantic = _resolve_semantic(sel, var_map, object_keys, alias_map, inline_field_map)
+        if semantic:
+            key, intent_expr, sel_expr = semantic
+            changes.append(f"locator(...).click → {h}.clickWithHealing (key={key})")
+            return f"await {h}.clickWithHealing('{key}', {sel_expr}, {intent_expr})"
+        key = _next_dyn_key()
+        changes.append(f"locator(...).click → {h}.clickWithHealing (dyn key={key})")
+        return f"await {h}.clickWithHealing('{key}', {sel}, {_intent_for_dyn(sel)})"
+
+    def _loc_chain_fill(m: re.Match) -> str:
+        sel = m.group(1).strip().rstrip(",").strip()
+        val = m.group(2).strip().rstrip(",").strip()
+        if not _balanced(sel) or not _balanced(val):
+            return m.group(0)
+        semantic = _resolve_semantic(sel, var_map, object_keys, alias_map, inline_field_map)
+        if semantic:
+            key, intent_expr, sel_expr = semantic
+            changes.append(f"locator(...).fill → {h}.fillWithHealing (key={key})")
+            return f"await {h}.fillWithHealing('{key}', {sel_expr}, {val}, {intent_expr})"
+        key = _next_dyn_key()
+        changes.append(f"locator(...).fill → {h}.fillWithHealing (dyn key={key})")
+        return f"await {h}.fillWithHealing('{key}', {sel}, {val}, {_intent_for_dyn(sel)})"
+
+    def _goto(m: re.Match) -> str:
+        page_expr = m.group(1)
+        url       = m.group(2).strip()
+        action_key = _next_key(f"{prefix}_nav")
+        changes.append(f"page.goto + TimingHealer.waitForNetworkIdle (key={action_key})")
+        return (
+            f"await {page_expr}.goto({url}); "
+            f"await {t}.waitForNetworkIdle('{action_key}')"
+        )
+
+    def _expect_visible(m: re.Match) -> str:
+        locator = m.group(1).strip()
+        semantic = _resolve_semantic(locator, var_map, object_keys, alias_map, inline_field_map)
+        if semantic:
+            key, intent_expr, sel_expr = semantic
+            changes.append(f"expect.toBeVisible → {h}.assertVisibleWithHealing (key={key})")
+            return f"await {h}.assertVisibleWithHealing('{key}', {sel_expr}, {intent_expr})"
+        return m.group(0)
+
+    def _chained_click(m: re.Match) -> str:
+        var_name = m.group(1)
+        semantic = var_map.get(var_name)
+        if semantic:
+            key, intent_expr, sel_expr = semantic
+            changes.append(f"{var_name}.click → {h}.clickWithHealing (key={key})")
+            return f"await {h}.clickWithHealing('{key}', {sel_expr}, {intent_expr})"
+        return m.group(0)
+
+    def _chained_fill(m: re.Match) -> str:
+        var_name = m.group(1)
+        val = m.group(2).strip()
+        if not _balanced(val):
+            return m.group(0)
+        semantic = var_map.get(var_name)
+        if semantic:
+            key, intent_expr, sel_expr = semantic
+            changes.append(f"{var_name}.fill → {h}.fillWithHealing (key={key})")
+            return f"await {h}.fillWithHealing('{key}', {sel_expr}, {val}, {intent_expr})"
+        return m.group(0)
+
+    # ── Balanced-paren rewriters ─────────────────────────────────────────────
+    # The action regexes below match only up to the `(` — the actual argument
+    # list is extracted via _extract_call_args which honours nested parens,
+    # strings, and template literals (so `fill(X, String(visitorCount))` is
+    # captured correctly). Each helper inspects the args and returns either
+    # the rewritten call or None to leave the original intact.
+
+    def _build_click_rewriter(label: str):
+        def rewrite(_prefix: str, args: list[str]) -> str | None:
+            if len(args) != 1:
+                return None
+            sel = args[0].strip()
+            if not sel:
+                return None
+            semantic = _resolve_semantic(sel, var_map, object_keys, alias_map, inline_field_map)
+            if semantic:
+                key, intent_expr, sel_expr = semantic
+                changes.append(f"{label} → {h}.clickWithHealing (key={key})")
+                return f"await {h}.clickWithHealing('{key}', {sel_expr}, {intent_expr})"
+            key = _next_dyn_key()
+            changes.append(f"{label} → {h}.clickWithHealing (dyn key={key})")
+            return f"await {h}.clickWithHealing('{key}', {sel}, {_intent_for_dyn(sel)})"
+        return rewrite
+
+    def _build_fill_rewriter(label: str):
+        def rewrite(_prefix: str, args: list[str]) -> str | None:
+            if len(args) != 2:
+                return None
+            sel, val = args[0].strip(), args[1].strip()
+            if not sel or not val:
+                return None
+            semantic = _resolve_semantic(sel, var_map, object_keys, alias_map, inline_field_map)
+            if semantic:
+                key, intent_expr, sel_expr = semantic
+                changes.append(f"{label} → {h}.fillWithHealing (key={key})")
+                return f"await {h}.fillWithHealing('{key}', {sel_expr}, {val}, {intent_expr})"
+            key = _next_dyn_key()
+            changes.append(f"{label} → {h}.fillWithHealing (dyn key={key})")
+            return f"await {h}.fillWithHealing('{key}', {sel}, {val}, {_intent_for_dyn(sel)})"
+        return rewrite
+
+    # Prefix patterns end at `(` so the scanner takes over from there. Order
+    # matters: longer / more-specific patterns are scanned first so a chained
+    # `.locator(X).click()` is consumed before the bare `page.click(...)`
+    # rule would even see it.
+    _PRE_LOC_CHAIN_FILL = re.compile(
+        rf"{_AWAIT_OPT}{_PAGE_EXPR}\s*\.\s*locator\([^)]*?\)\s*\.\s*fill\("
+    )
+    _PRE_LOC_CHAIN_CLICK = re.compile(
+        rf"{_AWAIT_OPT}{_PAGE_EXPR}\s*\.\s*locator\([^)]*?\)\s*\.\s*click\("
+    )
+    _PRE_WRAPPER_FILL = re.compile(
+        rf"{_AWAIT_OPT}(?:this\s*\.\s*)?base\s*\.\s*waitAndFill(?:ByTestId)?\("
+    )
+    _PRE_WRAPPER_CLICK = re.compile(
+        rf"{_AWAIT_OPT}(?:this\s*\.\s*)?base\s*\.\s*waitAndClick(?:ByTestId)?\("
+    )
+    _PRE_FILL = re.compile(rf"{_AWAIT_OPT}{_PAGE_EXPR}\s*\.\s*fill\(")
+    _PRE_CLICK = re.compile(rf"{_AWAIT_OPT}{_PAGE_EXPR}\s*\.\s*click\(")
+
+    # Chained-locator click/fill: the selector is the first arg of
+    # `locator(SEL)`, NOT an arg of `click()` / `fill()`. We need a
+    # bespoke rewriter that hops back to the inner locator() args.
+    def _build_loc_chain_rewriter(action: str, label: str):
+        def rewrite(prefix_text: str, args: list[str]) -> str | None:
+            # `args` here are the args of click(...) / fill(...). The
+            # selector lives in the preceding `locator(...)` call.
+            loc_match = re.search(rf"locator\(([^)]*?)\)\s*\.\s*{action}\(", prefix_text)
+            if not loc_match:
+                return None
+            sel = loc_match.group(1).strip()
+            if not sel:
+                return None
+            if action == "click":
+                if args and any(a for a in args):
+                    return None  # click() must be no-arg
+                semantic = _resolve_semantic(sel, var_map, object_keys, alias_map, inline_field_map)
+                if semantic:
+                    key, intent_expr, sel_expr = semantic
+                    changes.append(f"{label} → {h}.clickWithHealing (key={key})")
+                    return f"await {h}.clickWithHealing('{key}', {sel_expr}, {intent_expr})"
+                key = _next_dyn_key()
+                changes.append(f"{label} → {h}.clickWithHealing (dyn key={key})")
+                return f"await {h}.clickWithHealing('{key}', {sel}, {_intent_for_dyn(sel)})"
+            if action == "fill":
+                if len(args) != 1:
+                    return None
+                val = args[0].strip()
+                if not val:
+                    return None
+                semantic = _resolve_semantic(sel, var_map, object_keys, alias_map, inline_field_map)
+                if semantic:
+                    key, intent_expr, sel_expr = semantic
+                    changes.append(f"{label} → {h}.fillWithHealing (key={key})")
+                    return f"await {h}.fillWithHealing('{key}', {sel_expr}, {val}, {intent_expr})"
+                key = _next_dyn_key()
+                changes.append(f"{label} → {h}.fillWithHealing (dyn key={key})")
+                return f"await {h}.fillWithHealing('{key}', {sel}, {val}, {_intent_for_dyn(sel)})"
+            return None
+        return rewrite
+
+    content = _scan_and_rewrite(content, _PRE_LOC_CHAIN_FILL, _build_loc_chain_rewriter("fill", "locator(...).fill"))
+    content = _scan_and_rewrite(content, _PRE_LOC_CHAIN_CLICK, _build_loc_chain_rewriter("click", "locator(...).click"))
+    content = _scan_and_rewrite(content, _PRE_WRAPPER_FILL, _build_fill_rewriter("base.waitAndFill*"))
+    content = _scan_and_rewrite(content, _PRE_WRAPPER_CLICK, _build_click_rewriter("base.waitAndClick*"))
+    content = _scan_and_rewrite(content, _PRE_FILL, _build_fill_rewriter("page.fill"))
+    content = _scan_and_rewrite(content, _PRE_CLICK, _build_click_rewriter("page.click"))
+
+    # Chained-on-variable patterns are still simple enough for regex; they
+    # don't take user-supplied args with nested parens.
+    content = _CHAINED_CLICK_RE.sub(_chained_click, content)
+    content = _CHAINED_FILL_RE.sub(_chained_fill, content)
+    # check/uncheck/selectOption: no healing wrapper in scaffold — leave as raw Playwright
+    content = _GOTO_RE.sub(_goto, content)
+    content = _EXPECT_VISIBLE_RE.sub(_expect_visible, content)
+    content = _inject_selector_accesses(content, changes, object_keys, alias_map, inline_field_map)
+    return content
+
+
+# ---------------------------------------------------------------------------
+# Selector-access injection — post-pass that appends `.selector` to bare
+# locator references (`xxxLocators.foo`, aliased `this.Elements.foo`, etc.)
+# that the healer-rewrite passes above didn't already cover.
+#
+# Why this exists: `locator_registrar.transform_locator_file` turns plain
+# string locator values into `{ selector, intent, stability }` objects so the
+# LocatorHealer has metadata to work with. Call sites that still take a raw
+# selector (`page.locator(...)`, `page.selectOption(...)`, custom wrappers like
+# `base.waitAndClick(...)`) compile against `string`, so without an explicit
+# `.selector` access they would receive the object and fail with TS2345.
+#
+# We only wrap keys known to be object-valued (`object_keys` map), and we skip
+# accesses that are already followed by `.selector`/`.intent`/`.stability` or
+# a function call (`(`). This keeps the transform idempotent and side-effect
+# free on already-fixed code.
+# ---------------------------------------------------------------------------
+
+# `<obj>.<key>` not followed by another `.something` or `(`. Used for both the
+# direct `xxxLocators.foo` form and aliased `this.Elements.foo` form (built
+# below at runtime from detected alias assignments).
+_BARE_LOCATOR_ACCESS_RE = re.compile(
+    r"\b(\w+Locators)\.(\w+)\b"
+    r"(?!\s*\.\s*\w)"     # not followed by another property access
+    r"(?!\s*\()"           # not followed by a function call
+)
+
+# Alias detection — locator object stored under another name.
+#   `const E = fooLocators;`
+#   `let E = fooLocators;`
+#   `private Elements = fooLocators;`  (with optional access modifiers / readonly)
+#   `private readonly Elements: <type> = fooLocators;`
+_ALIAS_VAR_RE = re.compile(
+    r"\b(?:const|let|var)\s+(\w+)(?:\s*:\s*[^=;]+)?\s*=\s*(\w+Locators)\s*;"
+)
+_ALIAS_FIELD_RE = re.compile(
+    r"\b(?:(?:private|public|protected|readonly|static)\s+)+(\w+)"
+    r"(?:\s*:\s*[^=;]+)?\s*=\s*(\w+Locators)\s*;"
+)
+
+# Inline-object class field that re-exports selectors from existing locator
+# objects, e.g.:
+#
+#   private MassInviteElements = {
+#     selectAllCheckbox: membersListPageLocators.selectAllCheckbox.selector,
+#     memberCheckbox:    membersListPageLocators.memberCheckbox.selector,
+#     ...
+#   };
+#
+# Each value is a `.selector` reference into a registered xxxLocators object,
+# so callers like `this.MassInviteElements.selectAllCheckbox` are runtime
+# strings. We extract these inline fields so the healer rewriter can route
+# them through `_healer.<...>WithHealing` using the original locator's
+# semantic info (key, intent, selector).
+_INLINE_FIELD_OPEN_RE = re.compile(
+    r"\b(?:(?:private|public|protected|readonly|static)\s+)+(\w+)"
+    r"(?:\s*:\s*[^={};]+)?\s*=\s*\{",
+)
+_INLINE_FIELD_ENTRY_RE = re.compile(
+    r"^\s*(\w+)\s*:\s*(\w+Locators)\.(\w+)\.selector\s*,?\s*$",
+    re.MULTILINE,
+)
+
+
+def _collect_alias_map(content: str) -> dict[str, str]:
+    """
+    Return aliases: `{ alias_access → locator_obj_name }`.
+
+    For local vars (`const E = fooLocators;`), the alias access is the bare
+    name (`E`). For class fields (`private Elements = fooLocators;`), the
+    alias access is `this.<name>` (e.g. `this.Elements`).
+    """
+    aliases: dict[str, str] = {}
+    for m in _ALIAS_VAR_RE.finditer(content):
+        aliases[m.group(1)] = m.group(2)
+    for m in _ALIAS_FIELD_RE.finditer(content):
+        aliases[f"this.{m.group(1)}"] = m.group(2)
+    return aliases
+
+
+def _collect_inline_field_map(content: str) -> dict[tuple[str, str], tuple[str, str]]:
+    """
+    Return `{ (alias_access, inline_key) → (locator_obj_name, original_key) }`
+    for inline class-field locator dictionaries that re-export
+    `<xxxLocators>.<key>.selector` entries.
+
+    Allows the healer rewriter to treat
+        `this.MassInviteElements.selectAllCheckbox`
+    as the equivalent of
+        `membersListPageLocators.selectAllCheckbox`
+    when generating `_healer.clickWithHealing(...)` calls.
+    """
+    mapping: dict[tuple[str, str], tuple[str, str]] = {}
+    for m in _INLINE_FIELD_OPEN_RE.finditer(content):
+        field_name = m.group(1)
+        brace_idx  = content.find("{", m.start())
+        if brace_idx < 0:
+            continue
+        # Find matching `}` with depth counting so nested object literals
+        # inside the field don't confuse us.
+        depth = 1
+        i = brace_idx + 1
+        while i < len(content) and depth > 0:
+            c = content[i]
+            if c == "{":
+                depth += 1
+            elif c == "}":
+                depth -= 1
+            i += 1
+        body = content[brace_idx + 1 : i - 1]
+        alias_access = f"this.{field_name}"
+        # Each well-formed entry: `key: xxxLocators.prop.selector,`
+        for em in _INLINE_FIELD_ENTRY_RE.finditer(body):
+            inline_key = em.group(1)
+            loc_name   = em.group(2)
+            orig_key   = em.group(3)
+            mapping[(alias_access, inline_key)] = (loc_name, orig_key)
+    return mapping
+
+
+def _inject_selector_accesses(
+    content: str,
+    changes: list[str],
+    object_keys: dict[str, set[str]] | None,
+    alias_map: dict[str, str] | None = None,
+    inline_field_map: dict[tuple[str, str], tuple[str, str]] | None = None,
+) -> str:
+    if not object_keys:
+        return content
+
+    n_changes = 0
+
+    # Pass 1 — direct `xxxLocators.key` references.
+    def _wrap_direct(m: re.Match) -> str:
+        nonlocal n_changes
+        obj, key = m.group(1), m.group(2)
+        if key not in object_keys.get(obj, set()):
+            return m.group(0)
+        n_changes += 1
+        return f"{obj}.{key}.selector"
+
+    content = _BARE_LOCATOR_ACCESS_RE.sub(_wrap_direct, content)
+
+    # Pass 2 — aliased references (`this.Elements.key`, `E.key`). Re-detect
+    # if no map was supplied (back-compat); callers in _replace_actions
+    # pass the already-collected map to avoid double work.
+    aliases = alias_map if alias_map is not None else _collect_alias_map(content)
+    for alias, locator_obj in aliases.items():
+        keys = object_keys.get(locator_obj)
+        if not keys:
+            continue
+        # Build a regex matching `<alias>.<key>` for the keys in this object.
+        # `alias` may contain `.` (e.g. `this.Elements`); escape it.
+        alias_re = re.compile(
+            rf"(?<!\.\.\.){re.escape(alias)}\.(\w+)\b"
+            rf"(?!\s*\.\s*\w)"
+            rf"(?!\s*\()"
+        )
+
+        def _wrap_alias(m: re.Match) -> str:
+            nonlocal n_changes
+            key = m.group(1)
+            if key not in keys:
+                return m.group(0)
+            n_changes += 1
+            return f"{alias}.{key}.selector"
+
+        content = alias_re.sub(_wrap_alias, content)
+
+    if n_changes:
+        changes.append(f"Appended .selector to {n_changes} locator references")
+    return content