vue3-migration 1.0.0

package/vue3_migration/reporting/markdown.py

@@ -0,0 +1,202 @@
+"""
+Markdown report generation for migration analysis results.
+"""
+
+from pathlib import Path
+
+from ..models import MixinEntry
+from .terminal import md_green, md_yellow
+
+
+def build_component_report(
+    component_path: Path,
+    mixin_entries: list[MixinEntry],
+    project_root: Path,
+) -> str:
+    """Build a markdown migration report for a single component."""
+    lines: list[str] = []
+    w = lines.append
+
+    try:
+        component_rel = component_path.relative_to(project_root)
+    except ValueError:
+        component_rel = component_path
+
+    w(f"# Migration Report: {md_green(str(component_rel))}\n")
+
+    ready_entries = []
+    blocked_entries = []
+
+    for entry in mixin_entries:
+        mixin_name = entry.mixin_stem
+        w(f"## Mixin: {mixin_name}\n")
+        w(f"**File:** {md_green(str(entry.mixin_path))}\n")
+
+        # Members breakdown
+        for section in ("data", "computed", "methods"):
+            section_members = getattr(entry.members, section)
+            if section_members:
+                w(f"**{section}:** {', '.join(section_members)}\n")
+
+        # Lifecycle hooks
+        if entry.lifecycle_hooks:
+            w(f"\n**Lifecycle hooks:** {', '.join(entry.lifecycle_hooks)}")
+            w("> Must be manually migrated (e.g. `mounted` -> `onMounted`).\n")
+
+        # Used members
+        used = entry.used_members
+        w(f"\n**Used by component:** {', '.join(used) if used else 'none detected'}\n")
+
+        # Composable analysis
+        comp = entry.composable
+        cls = entry.classification
+
+        if not entry.used_members:
+            w("**Status: READY** -- no members used, mixin can be safely removed.\n")
+            ready_entries.append(entry)
+        elif not comp or not cls:
+            w(f"**Composable:** {md_yellow('NOT FOUND')}\n")
+            blocked_entries.append(entry)
+        else:
+            w(f"**Composable:** {md_green(str(comp.file_path))}")
+            w(f"**Function:** `{comp.fn_name}`")
+            w(f"**Import path:** `{comp.import_path}`")
+            w(f"> {md_yellow('Verify the above path and function name are correct.')}\n")
+
+            if cls.truly_missing:
+                w(f"**MISSING from composable:** {', '.join(cls.truly_missing)}\n")
+            if cls.overridden:
+                w(f"**Overridden by component:** {', '.join(cls.overridden)}")
+                w("> These mixin members are redefined in the component itself, "
+                  "so the composable doesn't need to provide them.\n")
+
+            if cls.truly_not_returned:
+                w(f"**NOT in return statement:** {', '.join(cls.truly_not_returned)}")
+                w("> These exist in the composable but are not returned, "
+                  "so the component cannot access them.\n")
+            if cls.overridden_not_returned:
+                w(f"**Overridden (not returned):** {', '.join(cls.overridden_not_returned)}")
+                w("> Not returned by composable, but the component defines them itself.\n")
+
+            if cls.is_ready:
+                status_note = ""
+                override_count = len(cls.overridden) + len(cls.overridden_not_returned)
+                if override_count:
+                    status_note = f" ({override_count} member(s) overridden by component)"
+                w(f"**Status: READY**{status_note} -- all needed members are present and returned.\n")
+                ready_entries.append(entry)
+            else:
+                blocked_entries.append(entry)
+
+        w("---\n")
+
+    # --- Actionable Summary ---
+    w("\n## Action Items\n")
+
+    if blocked_entries:
+        for entry in blocked_entries:
+            mixin_name = entry.mixin_stem
+            comp = entry.composable
+            cls = entry.classification
+
+            if not comp:
+                w(f"### {mixin_name}: Create composable")
+                w(f"- {md_yellow('A composable needs to be created')} for `{mixin_name}`.")
+                if entry.used_members:
+                    w(f"- It must expose: {', '.join(entry.used_members)}\n")
+            else:
+                w(f"### {mixin_name}: Update `{comp.fn_name}`")
+                if cls and cls.missing:
+                    w(f"- Add to composable: {', '.join(cls.missing)}")
+                if cls and cls.not_returned:
+                    w(f"- Add to return statement: {', '.join(cls.not_returned)}")
+                w(f"- File: {md_green(str(comp.file_path))}\n")
+
+    if ready_entries:
+        w("### Ready for injection")
+        for entry in ready_entries:
+            if not entry.used_members:
+                w(f"- `{entry.mixin_stem}` -- no members used, will just remove mixin")
+            else:
+                comp = entry.composable
+                w(f"- `{entry.mixin_stem}` -> `{comp.fn_name}` ({len(entry.used_members)} members)")
+        w("")
+
+    if not blocked_entries:
+        w("All mixins are ready. Run the script again to inject.\n")
+    elif ready_entries:
+        w(f"{len(ready_entries)} of {len(mixin_entries)} mixin(s) are ready for partial injection.\n")
+    else:
+        w(f"{md_yellow('No mixins are ready for injection yet.')} Fix the issues above and re-run.\n")
+
+    return "\n".join(lines)
+
+
+def build_audit_report(
+    mixin_path: Path,
+    members: dict[str, list[str]],
+    lifecycle_hooks: list[str],
+    importing_files: list[Path],
+    all_member_names: list[str],
+    composable_path_arg: str | None,
+    composable_identifiers: list[str],
+    composable_exists: bool,
+    project_root: Path,
+    usage_map: dict[str, list[str]],
+) -> str:
+    """Build a markdown audit report for a single mixin."""
+    lines: list[str] = []
+    w = lines.append
+
+    w(f"# Mixin Audit: {mixin_path.name}\n")
+
+    w("## Mixin Members\n")
+    for section in ("data", "computed", "methods"):
+        if members[section]:
+            w(f"**{section}:** {', '.join(members[section])}\n")
+
+    w("\n## Lifecycle Hooks\n")
+    if lifecycle_hooks:
+        w(f"{', '.join(lifecycle_hooks)}\n")
+        w("\n> These hooks contain logic that must be manually migrated "
+          "to the composable (e.g. `mounted` -> `onMounted`).\n")
+    else:
+        w("*No lifecycle hooks found in this mixin.*\n")
+
+    w(f"\n## Files Importing the Mixin ({len(importing_files)})\n")
+
+    for file_path in sorted(importing_files):
+        relative_path = file_path.relative_to(project_root)
+        used = usage_map.get(str(relative_path), [])
+        w(f"### {relative_path}\n")
+        if used:
+            w(f"Uses: {', '.join(used)}\n")
+        else:
+            w("Uses: *(none detected -- mixin may be unused here)*\n")
+
+    all_used_members = sorted(set(
+        member for used_list in usage_map.values() for member in used_list
+    ))
+
+    w("\n## Composable Status\n")
+    if not composable_path_arg:
+        w("**No composable path provided.** A composable should be created.\n")
+    elif not composable_exists:
+        w(f"**Composable file not found at `{composable_path_arg}`.** It should be created.\n")
+    else:
+        missing = [m for m in all_used_members if m not in composable_identifiers]
+        if missing:
+            w(f"**Missing from composable:** {', '.join(missing)}\n")
+        else:
+            w("All used members are present in the composable.\n")
+
+    w("\n## Summary\n")
+    w(f"- Total mixin members: {len(all_member_names)}\n")
+    w(f"- Lifecycle hooks: {len(lifecycle_hooks)}\n")
+    w(f"- Members used across codebase: {len(all_used_members)}\n")
+
+    unused_members = [m for m in all_member_names if m not in all_used_members]
+    if unused_members:
+        w(f"- Unused members (candidates for removal): {', '.join(unused_members)}\n")
+
+    return "\n".join(lines)

package/vue3_migration/reporting/terminal.py

@@ -0,0 +1,61 @@
+"""
+Terminal output helpers — ANSI colors and formatting for CLI display.
+"""
+
+import sys
+
+# ANSI escape codes
+_GREEN = "\033[32m"
+_YELLOW = "\033[33m"
+_RED = "\033[31m"
+_CYAN = "\033[36m"
+_BOLD = "\033[1m"
+_DIM = "\033[2m"
+_RESET = "\033[0m"
+
+
+def supports_color() -> bool:
+    """Check if the terminal supports ANSI color codes."""
+    if not hasattr(sys.stdout, "isatty"):
+        return False
+    if not sys.stdout.isatty():
+        return False
+    return True
+
+
+def green(text: str) -> str:
+    return f"{_GREEN}{text}{_RESET}"
+
+
+def yellow(text: str) -> str:
+    return f"{_YELLOW}{text}{_RESET}"
+
+
+def red(text: str) -> str:
+    return f"{_RED}{text}{_RESET}"
+
+
+def cyan(text: str) -> str:
+    return f"{_CYAN}{text}{_RESET}"
+
+
+def bold(text: str) -> str:
+    return f"{_BOLD}{text}{_RESET}"
+
+
+def dim(text: str) -> str:
+    return f"{_DIM}{text}{_RESET}"
+
+
+def red_bold(text: str) -> str:
+    return f"{_RED}{_BOLD}{text}{_RESET}"
+
+
+# -- Markdown colors (inline HTML for reports) --
+
+def md_green(text: str) -> str:
+    return f'<span style="color:#2ea043">{text}</span>'
+
+
+def md_yellow(text: str) -> str:
+    return f'<span style="color:#d29922">{text}</span>'

package/vue3_migration/transform/injector.py

@@ -0,0 +1,134 @@
+"""
+Code injection — add/remove imports, manipulate mixins arrays, inject setup() functions.
+
+All functions operate on source text strings and return modified text.
+They do NOT perform file I/O — callers handle reading/writing.
+"""
+
+import re
+
+from ..core.js_parser import extract_brace_block
+
+
+def add_composable_import(content: str, fn_name: str, import_path: str) -> str:
+    """Add composable import at the top of <script>. No-op if already present."""
+    if re.search(rf"\b{re.escape(fn_name)}\b", content):
+        return content
+
+    import_line = f"import {{ {fn_name} }} from '{import_path}'\n"
+
+    # Insert after <script> tag
+    script_match = re.search(r"(<script[^>]*>\s*\n?)", content)
+    if script_match:
+        pos = script_match.end()
+        return content[:pos] + import_line + content[pos:]
+
+    # For .js/.ts: after the last existing import
+    last_import = None
+    for match in re.finditer(r"^import\s+.+$", content, re.MULTILINE):
+        last_import = match
+    if last_import:
+        pos = last_import.end() + 1
+        return content[:pos] + import_line + content[pos:]
+
+    return import_line + content
+
+
+def remove_import_line(content: str, mixin_stem: str) -> str:
+    """Delete the import line for a specific mixin."""
+    pattern = rf"""^[ \t]*import\s+\w+\s+from\s+['"].*?{re.escape(mixin_stem)}(?:\.(?:js|ts))?['"].*\n?"""
+    return re.sub(pattern, "", content, count=1, flags=re.MULTILINE)
+
+
+def remove_mixin_from_array(content: str, local_name: str) -> str:
+    """Remove a mixin from `mixins: [...]`. Drops the whole line if array empties."""
+    match = re.search(r"(\s*)mixins\s*:\s*\[([^\]]*)\](\s*,?)", content)
+    if not match:
+        return content
+
+    indent, inner, trailing = match.group(1), match.group(2), match.group(3)
+    items = [x.strip() for x in inner.split(",") if x.strip()]
+    remaining = [x for x in items if x != local_name]
+
+    if not remaining:
+        return re.sub(r"[ \t]*mixins\s*:\s*\[[^\]]*\]\s*,?[ \t]*\n?", "", content, count=1)
+
+    rebuilt = f"{indent}mixins: [{', '.join(remaining)}]{trailing}"
+    return content[:match.start()] + rebuilt + content[match.end():]
+
+
+def inject_setup(
+    content: str,
+    composable_calls: list[tuple[str, list[str]]],
+    indent: str = "  ",
+) -> str:
+    """Create or merge setup() with multiple composable destructuring calls.
+
+    Args:
+        content: The component source text.
+        composable_calls: List of (fn_name, [member1, member2, ...]) tuples.
+        indent: Indentation string (default 2 spaces).
+
+    Returns:
+        Modified source text with setup() containing all composable calls.
+    """
+    all_returned_members = []
+    call_lines = []
+    for fn_name, members in composable_calls:
+        call_lines.append(f"{indent}{indent}const {{ {', '.join(members)} }} = {fn_name}()")
+        all_returned_members.extend(members)
+
+    # --- Existing setup(): prepend calls, merge into return ---
+    setup_match = re.search(r"\bsetup\s*\([^)]*\)\s*\{", content)
+    if setup_match:
+        # Insert composable calls as first lines
+        insert_pos = setup_match.end()
+        injection = "\n" + "\n".join(call_lines) + "\n"
+        content = content[:insert_pos] + injection + content[insert_pos:]
+
+        # Merge members into existing return statement
+        ret_match = re.search(r"\breturn\s*\{", content[setup_match.start():])
+        if ret_match:
+            abs_pos = setup_match.start() + ret_match.end()
+            block_start = abs_pos - 1
+            existing_return = extract_brace_block(content, block_start)
+            existing_keys = set(re.findall(r"\b(\w+)\b", existing_return))
+            new_keys = [m for m in all_returned_members if m not in existing_keys]
+            if new_keys:
+                content = content[:abs_pos] + " " + ", ".join(new_keys) + "," + content[abs_pos:]
+        else:
+            # No return yet -- add one before closing brace
+            body_start = setup_match.end() - 1
+            body = extract_brace_block(content, body_start)
+            close_pos = body_start + 1 + len(body)
+            ret_stmt = f"\n{indent}{indent}return {{ {', '.join(all_returned_members)} }}\n{indent}"
+            content = content[:close_pos] + ret_stmt + content[close_pos:]
+
+        return content
+
+    # --- No setup(): create one ---
+    lines = [f"{indent}setup() {{"]
+    lines.extend(call_lines)
+    lines.append("")
+    lines.append(f"{indent}{indent}return {{ {', '.join(all_returned_members)} }}")
+    lines.append(f"{indent}}},")
+    setup_block = "\n".join(lines) + "\n"
+
+    # Insert before data()
+    data_match = re.search(r"^(\s*)data\s*\(\s*\)\s*\{", content, re.MULTILINE)
+    if data_match:
+        return content[:data_match.start()] + setup_block + content[data_match.start():]
+
+    # Fallback: after export default {
+    export_match = re.search(r"export\s+default\s*\{[ \t]*\n?", content)
+    if export_match:
+        return content[:export_match.end()] + setup_block + content[export_match.end():]
+
+    return content
+
+
+def find_mixin_import_name(content: str, mixin_stem: str) -> str | None:
+    """Find the local import name for a mixin by its file stem."""
+    pattern = rf"""import\s+(\w+)\s+from\s+['"].*?{re.escape(mixin_stem)}(?:\.(?:js|ts))?['"]"""
+    match = re.search(pattern, content)
+    return match.group(1) if match else None