@qa-gentic/stlc-agents 1.0.27 → 1.0.28

package/src/stlc_agents/agent_migration/mapper.py

@@ -0,0 +1,439 @@
+"""Map source test files to their roles and Helix-QA target paths."""
+from __future__ import annotations
+import re
+from collections import defaultdict
+from pathlib import Path
+
+
+_SKIP_DIRS = {
+    "node_modules", "dist", ".venv", "__pycache__", ".git",
+    "build", "coverage", ".next", "out", ".nyc_output",
+    "test-results", "playwright-report", "allure-results", "allure-report",
+}
+
+# Fix 1: removed *constants* — config/enum files are not locators
+_LOCATOR_RE = [
+    re.compile(r".*[Ll]ocators?\.(js|ts)$"),
+    re.compile(r".*[Ss]electors?\.(js|ts)$"),
+    re.compile(r".*\.locators?\.(js|ts)$"),
+]
+
+_PAGE_OBJ_RE = [
+    re.compile(r".*[Pp]age\.(js|ts)$"),
+    re.compile(r".*\.page\.(js|ts)$"),
+    re.compile(r".*[Pp]age[Oo]bject\.(js|ts)$"),
+    re.compile(r".*[Pp][Oo]\.(js|ts)$"),
+]
+
+_STEP_DEF_RE = [
+    re.compile(r".*\.steps\.(js|ts)$"),
+    re.compile(r".*[Ss]teps?\.(js|ts)$"),
+    re.compile(r".*(step[_-]?definitions?|stepDefinitions?)/.*\.(js|ts)$", re.IGNORECASE),
+]
+
+_FEATURE_RE = [re.compile(r".*\.feature$")]
+
+_CONFIG_RE = {
+    "config_playwright": [re.compile(r"playwright\.config\.(js|ts)$")],
+    "config_cucumber":   [re.compile(r"cucumber\.(js|cjs|mjs)$")],
+    "config_tsconfig":   [re.compile(r"tsconfig(\..+)?\.json$")],
+    "config_package":    [re.compile(r"package\.json$")],
+}
+
+# ── Helpers / utilities ─────────────────────────────────────────────────────
+# Anything under a helper/helpers/utils/util directory or matching .helper / .util suffix.
+# Includes .json/.txt data files inside the helper tree so test data migrates too.
+_HELPER_RE = [
+    re.compile(r"(?:^|.*[\\/])(helpers?|utils?)[\\/].*\.(js|ts|json|txt)$"),
+    re.compile(r".*\.helper\.(js|ts)$"),
+    re.compile(r".*\.util\.(js|ts)$"),
+    re.compile(r".*\.utils\.(js|ts)$"),
+]
+
+# ── API clients (commonly under pages/.../api/ in older layouts) ────────────
+# These behave like helpers — pure utility/page classes — so we route them under src/helper/api/
+_API_CLIENT_RE = [
+    re.compile(r"(?:^|.*[\\/])api[\\/][^\\/]+\.api\.(js|ts)$"),
+    re.compile(r".*\.api\.(js|ts)$"),
+]
+
+# ── Hooks (Cucumber + Playwright fixtures) ─────────────────────────────────
+# pageFixture, Before/After hooks, World definitions
+_HOOK_RE = [
+    re.compile(r"(?:^|.*[\\/])hooks?[\\/].*\.(js|ts)$"),
+    re.compile(r".*pageFixture\.(js|ts)$", re.IGNORECASE),
+    re.compile(r".*[\\/](world|Before|After)\.(js|ts)$"),
+]
+
+# ── Fixtures (Playwright fixtures, test data) ──────────────────────────────
+_FIXTURE_RE = [
+    re.compile(r"(?:^|.*[\\/])fixtures?[\\/].*\.(js|ts|json)$"),
+    re.compile(r".*\.fixture\.(js|ts)$"),
+]
+
+# ── Cucumber support files (World, custom params) ──────────────────────────
+_SUPPORT_RE = [
+    re.compile(r".*[\\/]support[\\/].*\.(js|ts)$"),
+]
+
+# ── Docker / containerisation ──────────────────────────────────────────────
+_DOCKER_RE = [
+    re.compile(r"(.*[\\/])?Dockerfile(\.[A-Za-z0-9_-]+)?$"),
+    re.compile(r"(.*[\\/])?docker-compose([.-][A-Za-z0-9_-]+)?\.(ya?ml)$"),
+    re.compile(r"(.*[\\/])?\.dockerignore$"),
+]
+
+# ── Environment files ──────────────────────────────────────────────────────
+_ENV_RE = [
+    re.compile(r"(.*[\\/])?\.env(\.[A-Za-z0-9_-]+)?$"),
+    re.compile(r"(.*[\\/])?\.env\.example$"),
+]
+
+# ── CI / CD pipelines ──────────────────────────────────────────────────────
+_CI_RE = [
+    re.compile(r"\.github[\\/]workflows[\\/].*\.(ya?ml)$"),
+    re.compile(r"\.gitlab-ci\.(ya?ml)$"),
+    re.compile(r"azure-pipelines(\.[A-Za-z0-9_-]+)?\.(ya?ml)$"),
+    re.compile(r"bitbucket-pipelines\.(ya?ml)$"),
+    re.compile(r"\.circleci[\\/]config\.(ya?ml)$"),
+]
+
+# ── Scripts (build / utility) ──────────────────────────────────────────────
+# Match scripts/foo.sh and bare run_qa.sh at the project root alike.
+_SCRIPT_RE = [
+    re.compile(r"(^|.*[\\/])scripts?[\\/].*\.(sh|ts|js|py)$"),
+    re.compile(r"^[^\\/]+\.sh$"),  # any shell script at the project root
+]
+
+# ── Playwright spec files (non-BDD source) ────────────────────────────────
+# `tests/**/*.spec.js` / `*.spec.ts` / `*.test.js` / `*.test.ts` from a
+# conventional Playwright project. These get split into a generated Gherkin
+# feature file plus a Cucumber step definition file, so the migrated project
+# is BDD-shaped even when the source was not.
+_PLAYWRIGHT_SPEC_RE = [
+    re.compile(r"(^|.*[\\/])tests?[\\/].*\.(spec|test)\.(js|ts)$"),
+    re.compile(r"^[^\\/]+\.(spec|test)\.(js|ts)$"),  # spec file at the project root
+]
+
+# Structural path segments that carry no meaningful domain information
+_STRUCTURAL = {
+    "src", "test", "tests", "steps", "features", "pages", "locators",
+    "utils", "helper", "helpers", "hooks", "config", "fixtures",
+    "support", "types", "interfaces", "models", "spec", "specs",
+}
+
+
+# ---------------------------------------------------------------------------
+# Kebab helpers
+# ---------------------------------------------------------------------------
+
+def _to_kebab(stem: str) -> str:
+    """Convert a filename stem to kebab-case, stripping known role suffixes."""
+    for suffix in ("Page", "Locators", "Selectors", "Steps", "PageObject", "PO"):
+        if stem.endswith(suffix):
+            stem = stem[: -len(suffix)]
+    stem = re.sub(r"([A-Z])", r"-\1", stem).lstrip("-").lower()
+    stem = re.sub(r"[_\s]+", "-", stem)
+    stem = re.sub(r"-{2,}", "-", stem).strip("-")
+    return stem or "unknown"
+
+
+def _dir_to_kebab(name: str) -> str:
+    """Convert a directory name to kebab-case (handles ALL_CAPS and CamelCase)."""
+    if name.isupper():
+        return name.lower()
+    result = re.sub(r"([A-Z])", r"-\1", name).lstrip("-").lower()
+    result = re.sub(r"[_\s]+", "-", result)
+    result = re.sub(r"-{2,}", "-", result).strip("-")
+    return result or name.lower()
+
+
+# Fix 3: CamelCase-aware kebab for feature filenames
+def _feature_kebab(stem: str) -> str:
+    """Convert a feature filename stem to kebab-case, preserving word boundaries."""
+    # Insert hyphen before each uppercase letter sequence start
+    result = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1-\2", stem)
+    result = re.sub(r"([a-z0-9])([A-Z])", r"\1-\2", result)
+    result = result.lower()
+    result = re.sub(r"[^a-z0-9]+", "-", result).strip("-")
+    return result or "unknown"
+
+
+# ---------------------------------------------------------------------------
+# Role detection
+# ---------------------------------------------------------------------------
+
+def _detect_role(rel: str) -> str:
+    # Order matters — more specific patterns first.
+    for pat in _LOCATOR_RE:
+        if pat.search(rel):
+            return "locator"
+    for pat in _PAGE_OBJ_RE:
+        if pat.search(rel):
+            return "page_object"
+    for pat in _STEP_DEF_RE:
+        if pat.search(rel):
+            return "step_def"
+    for pat in _FEATURE_RE:
+        if pat.search(rel):
+            return "feature"
+    # Playwright spec files take priority over the catch-all "unknown" role
+    # so the migrator can split them into feature+steps pairs.
+    for pat in _PLAYWRIGHT_SPEC_RE:
+        if pat.search(rel):
+            return "playwright_spec"
+    for role, patterns in _CONFIG_RE.items():
+        for pat in patterns:
+            if pat.search(rel):
+                return role
+    # Newly supported categories
+    for pat in _HOOK_RE:
+        if pat.search(rel):
+            return "hook"
+    for pat in _SUPPORT_RE:
+        if pat.search(rel):
+            return "support"
+    for pat in _FIXTURE_RE:
+        if pat.search(rel):
+            return "fixture"
+    for pat in _API_CLIENT_RE:
+        if pat.search(rel):
+            return "api_client"
+    for pat in _HELPER_RE:
+        if pat.search(rel):
+            return "helper"
+    for pat in _DOCKER_RE:
+        if pat.search(rel):
+            return "docker"
+    for pat in _ENV_RE:
+        if pat.search(rel):
+            return "env"
+    for pat in _CI_RE:
+        if pat.search(rel):
+            return "ci"
+    for pat in _SCRIPT_RE:
+        if pat.search(rel):
+            return "script"
+    return "unknown"
+
+
+# ---------------------------------------------------------------------------
+# Target path computation
+# ---------------------------------------------------------------------------
+
+def _helix_target(path: Path, role: str, rel: str | None = None) -> str | None:
+    stem = path.stem
+    rel  = rel or path.as_posix()
+
+    if role == "locator":
+        stem = re.sub(r"\.locators?$", "", stem, flags=re.IGNORECASE)
+        return f"src/locators/{_to_kebab(stem)}.locators.ts"
+
+    if role == "page_object":
+        stem = re.sub(r"\.page$", "", stem, flags=re.IGNORECASE)
+        return f"src/pages/{_to_kebab(stem)}.page.ts"
+
+    if role == "step_def":
+        stem = re.sub(r"\.steps?$", "", stem, flags=re.IGNORECASE)
+        return f"src/test/steps/{_to_kebab(stem)}.steps.ts"
+
+    if role == "playwright_spec":
+        # Strip .spec/.test suffixes from the stem; the generated steps file
+        # is written here, and the companion .feature file is derived from
+        # this path during migration (see _migrate.py).
+        stem = re.sub(r"\.(spec|test)$", "", stem, flags=re.IGNORECASE)
+        return f"src/test/steps/{_to_kebab(stem)}.steps.ts"
+
+    if role == "feature":
+        # Fix 3: CamelCase-aware conversion
+        return f"src/test/features/{_feature_kebab(path.stem)}.feature"
+
+    if role == "config_playwright":
+        return "playwright.config.ts"
+
+    if role == "config_cucumber":
+        # Emitted as CJS .js at root (not TS under src/) — cucumber-js can't
+        # load a .ts config without prior ts-node bootstrap. See
+        # config_merger.merge_cucumber_config.
+        return "config/cucumber.js"
+
+    if role == "config_package":
+        return "package.json"
+
+    if role == "config_tsconfig":
+        return "tsconfig.json"
+
+    # ── Helper: preserve sub-tree under src/helper/ ──────────────────────────
+    if role == "helper":
+        return f"src/helper/{_preserve_under(rel, ('helper', 'helpers', 'utils', 'util'))}"
+
+    # ── API client: flatten to src/helper/api/ ───────────────────────────────
+    if role == "api_client":
+        return f"src/helper/api/{path.name}"
+
+    # ── Hook: flat under src/hooks/ ──────────────────────────────────────────
+    if role == "hook":
+        return f"src/hooks/{path.name}"
+
+    # ── Fixture: preserve sub-tree under src/fixtures/ ───────────────────────
+    if role == "fixture":
+        return f"src/fixtures/{_preserve_under(rel, ('fixture', 'fixtures'))}"
+
+    # ── Support (Cucumber): flat under src/test/support/ ─────────────────────
+    if role == "support":
+        return f"src/test/support/{path.name}"
+
+    # ── Docker / env / scripts / CI: keep at original location relative to root
+    if role == "docker":
+        return path.name if "/" not in rel else rel  # keep at root, or preserve dir
+    if role == "env":
+        # If env file sits at the project root, target the project root.
+        # Otherwise preserve its nested location — many frameworks load
+        # `.env.<app>` from a fixed sub-path (e.g. src/helper/environment/).
+        if "/" not in rel:
+            return path.name
+        return rel
+    if role == "ci":
+        return rel  # preserve `.github/workflows/...` etc.
+    if role == "script":
+        # Preserve location: scripts/foo.sh stays under scripts/, but root-level
+        # run_qa.sh stays at root.
+        return rel
+
+    # ── Catch-all: any file not matched by a specific role is raw-copied to
+    # the same relative path it had in the source project. This keeps READMEs,
+    # docs (.md), license files, .gitignore, .editorconfig, vrt-baselines,
+    # arbitrary JSON data, etc. — anything the user dropped in the source —
+    # available in the migrated project.
+    if role == "unknown":
+        return rel
+
+    return None
+
+
+def _preserve_under(rel: str, parents: tuple[str, ...]) -> str:
+    """
+    Given a relative path like 'src/helper/dashboard/validation.helper.ts' and
+    parents like ('helper', 'helpers'), return the sub-path beneath the first
+    matching parent — e.g. 'dashboard/validation.helper.ts'.
+    Falls back to the filename if no parent matches.
+    """
+    parts = Path(rel).parts
+    for i, p in enumerate(parts):
+        if p.lower() in parents:
+            sub = "/".join(parts[i + 1 :])
+            return sub or parts[-1]
+    return parts[-1] if parts else rel
+
+
+# ---------------------------------------------------------------------------
+# Fix 2: Collision disambiguation
+# ---------------------------------------------------------------------------
+
+def _pick_prefix(rel: str, target_stem: str) -> str:
+    """
+    Walk the source path right-to-left and return the first directory segment
+    that is (a) not the target stem itself and (b) not a generic structural dir.
+    Falls back to any non-matching segment if all non-structural ones match.
+    """
+    parts = list(Path(rel).parts[:-1])  # directory parts only
+
+    # First pass: prefer non-structural, non-matching segments
+    for p in reversed(parts):
+        k = _dir_to_kebab(p)
+        if k and k != target_stem and k not in _STRUCTURAL:
+            return k
+
+    # Second pass: take any non-matching segment
+    for p in reversed(parts):
+        k = _dir_to_kebab(p)
+        if k and k != target_stem:
+            return k
+
+    return _dir_to_kebab(parts[-1]) if parts else "misc"
+
+
+def _disambiguate(mappings: list[dict]) -> list[dict]:
+    """
+    Detect target collisions and add a distinguishing directory prefix to
+    each colliding file's target path.  Runs up to 3 passes.
+    """
+    for _pass in range(3):
+        groups: dict[str, list[int]] = defaultdict(list)
+        for i, m in enumerate(mappings):
+            if m["target"]:
+                groups[m["target"]].append(i)
+
+        any_collision = False
+        for target, indices in groups.items():
+            if len(indices) <= 1:
+                continue
+            any_collision = True
+
+            target_path     = Path(target)
+            target_dir      = str(target_path.parent)
+            target_filename = target_path.name       # e.g. "organization.steps.ts"
+            target_stem     = target_filename.split(".")[0]  # e.g. "organization"
+
+            for idx in indices:
+                m      = mappings[idx]
+                prefix = _pick_prefix(m["relative"], target_stem)
+                m["target"] = f"{target_dir}/{prefix}-{target_filename}"
+
+        if not any_collision:
+            break
+
+    return mappings
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def map_source_files(source_dir: str) -> list[dict]:
+    """
+    Scan source_dir and return a list of file descriptors.
+
+    Each entry:
+        source         — absolute path
+        relative       — path relative to source_dir (forward slashes)
+        role           — locator | page_object | step_def | feature |
+                         config_playwright | config_cucumber | unknown
+        target         — Helix-relative target path, or None
+        stem           — filename stem
+        needs_js_to_ts — True when source is .js and target is .ts
+    """
+    root    = Path(source_dir)
+    results: list[dict] = []
+
+    for path in sorted(root.rglob("*")):
+        if not path.is_file():
+            continue
+        if any(s in path.parts for s in _SKIP_DIRS):
+            continue
+        # Skip OS / editor cruft that adds no value to the migrated project.
+        if path.name in {".DS_Store", "Thumbs.db"}:
+            continue
+
+        rel  = path.relative_to(root).as_posix()
+
+        # No extension filter — every surviving file is migrated. Files that
+        # don't match any specific role land in role="unknown" and are raw-copied
+        # at their original relative path by _helix_target / _migrate.py.
+
+        role = _detect_role(rel)
+        tgt  = _helix_target(path, role, rel)
+
+        results.append({
+            "source":         str(path),
+            "relative":       rel,
+            "role":           role,
+            "target":         tgt,
+            "stem":           path.stem,
+            "needs_js_to_ts": path.suffix == ".js" and tgt is not None and tgt.endswith(".ts"),
+        })
+
+    # Fix 2: resolve target-path collisions
+    _disambiguate(results)
+
+    return results

package/src/stlc_agents/agent_migration/reporter.py

@@ -0,0 +1,86 @@
+"""Generate MIGRATION-REPORT.md after a migration run."""
+from __future__ import annotations
+from datetime import datetime
+from pathlib import Path
+
+
+def generate_report(
+    helix_root: str,
+    source_dir: str,
+    framework: str,
+    written: list[dict],
+    skipped: list[dict],
+    conflicts: list[dict],
+    todos: list[str],
+) -> str:
+    """Write MIGRATION-REPORT.md to helix_root and return the absolute path."""
+    now = datetime.now().strftime("%Y-%m-%d %H:%M")
+
+    lines = [
+        "# Migration Report",
+        "",
+        f"**Generated:** {now}  ",
+        f"**Source:**    `{source_dir}`  ",
+        f"**Framework:** `{framework}`  ",
+        f"**Helix root:** `{helix_root}`",
+        "",
+        "---",
+        "",
+        "## Summary",
+        "",
+        "| Metric | Count |",
+        "|--------|-------|",
+        f"| Files written          | {len(written)} |",
+        f"| Files skipped          | {len(skipped)} |",
+        f"| Conflicts resolved     | {len(conflicts)} |",
+        f"| TODOs added            | {len(todos)} |",
+        "",
+    ]
+
+    if written:
+        lines += [
+            "## Migrated Files",
+            "",
+            "| Source | Target | Role | Changes |",
+            "|--------|--------|------|---------|",
+        ]
+        for f in written:
+            src     = f.get("source", "—")
+            tgt     = f.get("target", "—")
+            role    = f.get("role", "—")
+            chg     = f.get("change_count", 0)
+            lines.append(f"| `{src}` | `{tgt}` | {role} | {chg} |")
+        lines.append("")
+
+    if todos:
+        lines += ["## TODOs", ""]
+        for t in todos:
+            lines.append(f"- {t}")
+        lines.append("")
+
+    if skipped:
+        lines += ["## Skipped Files", ""]
+        for f in skipped:
+            src    = f.get("source", "—")
+            reason = f.get("reason", "unknown")
+            lines.append(f"- `{src}` — {reason}")
+        lines.append("")
+
+    if conflicts:
+        lines += ["## Conflicts Resolved", ""]
+        for c in conflicts:
+            path       = c.get("path", "—")
+            resolution = c.get("resolution", "unknown")
+            lines.append(f"- `{path}` — {resolution}")
+        lines.append("")
+
+    lines += [
+        "---",
+        "",
+        "> Generated by `qa-migration` — STLC Agents migration tool.",
+        "",
+    ]
+
+    report_path = Path(helix_root) / "MIGRATION-REPORT.md"
+    report_path.write_text("\n".join(lines), encoding="utf-8")
+    return str(report_path)